Recolourable Bi-State Objects
Notes on the requirements and quirks for recolourable bi-state objects.
Recolourable - An object having at least one mesh subset that can be recoloured.
Bi-state - An object having two different states (usually clean and dirty). Note, this article originally referred to "multi-state" objects, but having tested tri-state objects and found them NOT to work, bi-state it is!
Making an object recolourable requires the subset to be listed in the tsDesignModeEnabled block of the GMND resource ...
... and creating the MMAT/TXMT/TXTR scene graph chains for each recolour. There are many ways to do this and various tutorials are available.
When creating a recolour of a bi-state object, you need to create a MMAT/TXMT/TXTR set for each state. To do this you will need to understand how to clone and edit resources with SimPe directly.
Making an object bi-state requires some code to detect the change of state (eg how many times an object has been used) and then using the Change Material (0x006D) primitive to change the object to match its state.
Which then leads to the question "How do I find out which recolour an object has so I can select the correct TXMT for the code to change its state?"
To which the answer is "You can't!"
So how does a recolourable bi-state object know which TXMT to use for each state? By correctly setting up the MMAT, TXMT and STR# 0x0088 resources!
TXMT Requirements
TXMTs for the recolourable subset(s) of a bi-state object must conform to the naming convention "{cresname}_{subsetname}_{colour}_{state}_txmt"
cresname is the name of the object's CRES resource without the "_cres" suffix. So if the object's CRES is named "wh-test-box_cres", then {cresname} is "wh-test-box". The {cresname} cannot contain the underscore (_) character, so "wh_test_box" is NOT permitted.
subsetname is the name of the subset listed in the GMND's tsDesignModeEnabled block (which will be the same as "subsetName" value of the associated MMAT), eg "placeholder1". The {subsetname} cannot contain the underscore (_) character, so "placeholder_1" is NOT permitted.
colour is an arbitary colour name (red, green, teal, myfunkyhue, etc). The {colourname} cannot contain the underscore (_) character, so "my_funky_hue" is NOT permitted.
state is a semi-arbitary state name (clean, dirty, short, etc). There are major restrictions on the state name. The primary state MUST be called "clean", the secondary state can be any other 5-letter word, eg, "dirty", "short", "naked". (Known pairs to have worked are "clean/dirty", "clean/short" and "clean/naked". Known pairs to have failed are "dress/naked", "long/short" and "reveal/hidden") Again, the {statename} cannot contain the underscore (_) character.
STR# 0x0088 (Materials) Requirements
The STR# 0x0088 resource must only list the TXMT references for the states of the primary colour (the one with its associated MMAT resource's "defaultMaterial" value set to 1 (true).
Referencing any other colour/state TXMTs will inexplicable break the system! There is no need to reference them anyway.
MMAT Requirements
The MMAT for the main state of the primary colour must have its defaultMaterial value set to 1 (true), while all other MMATs for this object must have their defaultMaterial values set to 0 (false).
The MMATs for the different states of the same colour must have the same "family" value, and each colour must have a unique value - so use SimPe's Hash Generator to create these.
The MMATs for the same state of the different colours must have the same "objectStateIndex" value, and each state must have a unique value. It is recommended, but not required, to use the corresponding entry number from the STR# 0x0088 resource.
The MMATs for the main state (clean) must set the "materialStateFlags" value to 0 (show recolour in catalog), and the other state (dirty)must set the "materialStateFlags" value to 2 (hide recolour in catalog).
Myths
Some web resources state that it is necessary to add a block to the GMND with its name set to the recolourable subset and add entries to reference all the TXMTs. This is known to be unnecessary.
References
Aside
For completeness, there is another approach to recolourable bi-state objects, and that is NOT to design mode enable them but to add menu entries to change their colour. In this case, the object "knows" its own colour and can pick the corresponding TXMTs for the various states via the "CNOI copying design from T5" approach - see here and here.
Files