User Guide: Materials and Shaders
From AFXWiki
One of the most important capabilities offered by TGEA and T3D is the material system that utilizes both procedurally generated and custom programmed shaders.
AFX uses materials and shaders internally for some effects (most notably Zodiacs), but for AFX developers, the TGEA and T3D material systems are primarily used with afxModel effects.
In TGE, there is only limited control over the way materials are used on afxModels. Most of this control is simply the ability to adjust some basic material settings such as SelfIllumination and blend style. But in TGEA and T3D, afxModel materials are specified in the same way it's done for other Torque objects: by creating Material and CustomMaterial objects in a separate materials.cs script.
Mapping Materials
Material and CustomMaterial specifications are linked to texture-tags which are unique names within a game. Texture-tags are, in turn, linked to areas of dts and other model types by internal names that are determined by the tool or exporter that generated the model. The texture-tag for both Materials and CustomMaterials is determined by the mapTo field. It must be defined explicitly in CustomMaterials, but in Materials an unspecified texture-tag will automatically be derived from the baseTex name.
To specify Materials and/or CustomMaterials for an afxModel, simply define them in a materials.cs file and reference the afxModel's dts texture-tags using mapTo fields. At startup, TGEA or T3D finds and execs all materials.cs files it finds. To add new materials, you simply define them in a file called materials.cs in any subfolder that the engine searches for your project. Note, however, that the convention for loading materials this way is not mission or level-specific. All materials are loaded at initial startup (on clients) prior to any mission/level load, and are therefore shared by all missions.
Remapping Texture Tags
Each unique texture-tag name can have only one material associated with it. Although this makes it very easy to define materials and have them automatically applied to all models using a matching texture-tag, it also has a downside. Unless you've planned for this one-material-per-texture-tag limitation and carefully assigned your texture-tags within your models, you will eventually run into problems like this:
- Two of your models use the same texture-tag but you want them to have different materials.
- Two models have different texture-tags but you want them to share a material and you don't want to duplicate it.
- One model assigns the same texture-tag to different parts of the model and you would like to split these up and apply different materials to them.
You can always go back to the model sources and re-export them with new tags, but this isn't always convenient or even possible. For afxModels and ShapeBase objects, AFX provides a shortcut.
Both afxModelData and ShapeBaseData include a remapTextureTags field, which should be a string containing space separated remapping tokens. A remapping token is two names separated by a colon, ":". The first name should be a texture-tag that exists in the model, while the second is a new name to replace it with. The remapTextureTags string can have any number of remapping tokens as long as the total string length does not exceed 255.
Here is an example:
- remapTextureTags = "insectHead:insectEye insectHead:insectJaws";
In this case, the texture-tag insectHead is assigned to two distinct meshes within the model and remapTextureTags is used to assign new and different texture-tags to each. In cases like this, where you are remapping multiple texture-tags with the same name, you may have to study the original model, or experiment, to find out which is which and apply the mappings in the correct order.
Previous: User Guide: Miscellaneous Useful Things
