Can someone, (Crimson Wizard I imagine) please run me through the best practice for adding new engine features that conflict with old ones.
In this case I'd like to add multiplicative tinting. This will change the tint function from Tint(red,green,blue,saturation,lightness) to simply Tint(red,green,blue).
What are the steps I need to do this from a compatibility perspective and can you point me to any points in the code as good exemplars for this?
Hmm, that depends from what changes exactly are required.
1. If it is merely a new script function that sets up same character properties but in different way, then you only need to write and register a new function. Script API can register functions with same name but different number of parameters for backwards compatibility. In the Editor there may be only one function of this name though, therefore you should take the one with longest parameter list and make some parameters optional by assigning them a "default value" or "no value" that does not have any meaning in original function.
In your case it may be
Tint(int red, int green, int blue, int saturation = -1, int luminance = -1)
The example which we have in 3.3.1 is Character::ChangeRoom (which has a variant with 1 extra loop parameter).
2. If your feature requires to store more data, then you'll have to add some new variables. The solution here may be different depending on object class. Some classes cannot change the order of their first data fields because they are part of plugin interface (Character class is). Also, the objects that are stored in static script arrays (like characters) cannot change their size without adding a backward-compatible fix that would translate old script offsets into new ones.
E: I just checked the code, and I see that I've already added a support for this, but it needs minor tweak to make it work with new size of object. Plus test the thing; we have never used this for real purpose.
3. Of course, if you change the meaning of existing properties, you need to make sure that old algorithms and features that use them may "translate" them in an old way. If the new meaning is just an alternative, then there should be a sign to let know this.
4. If you are completely changing the way some algorithms/features work, there should be a conditional branch which checks game version. You can find examples everywhere. Usual check looks like:
if (loaded_game_file_version >= kGameVersion_270)
<...>
else
<...>
Quote from: Crimson Wizard on Thu 03/07/2014 12:23:04Tint(int red, int green, int blue, int saturation = -1, int luminance = -1)
Other built-in functions typically defer to the SCR_NO_VALUE macro for optional parameters.