Thunderbrd
C2C War Dog
Modder's Guide to the C2C Replacement Mechanism
Introduction
Since this has become a fairly stable mechanism and has been fairly well tested and proven at this point, and we've never really set forth exactly how to utilize this mechanism from an XML standpoint, this thread is intended to be that solid easy guide to follow to use the Replacement Mechanism.
Backing up here for clarity's sake, the Replacement Mechanism allows us to take any game object and write a complete replacement for that object for when a particular game situation exists. At the moment, this has been well tested with the contingent game situation being a game option, but AIAndy in his genius determined a far deeper way to make this work that has probably not been nearly as exploited as it well could be.
The condition is based on an advanced expression code and again, so far all examples make that boolean expression hinge on a game option and any other game situation has not been tested. However, conceivably, this can also be made to work off of Modder Game Options, Modder Options, and any other BUG option. It can make edit entries replace the core object if another object exists or does not, if a player has a particular status, pretty much any imaginable circumstance either in game setup or mid-game. If we want a building to change what it does entirely based on whether a unit anywhere has obtained a particular promotion, we can probably do just that with this system.
Of course, overuse of this mechanism can be highly problematic as it can introduce some tumorous modding practices. Whenever a replacement entry has been defined, it must be considered for adjustment whenever the primary entry it's replacing has been adjusted. In most cases, replacements are meant to introduce fairly small changes but can be as extreme or minor as the situation calls for. ls612's replacement traits for the Focused Traits option is an example of a complete rewrite of the same traits that exist in the core provided that the Focused Traits option is on.
Now, there WAS some discussion about making this structure work more along WoC lines, where a replacement entry can assume the original is correct EXCEPT in the case of any re-defined tags.
Why did we need this when we HAD the WoC structure already? Because WoC is limited only to the point of load and cannot redirect the definitions of a game object AFTER the mod has been loaded, or DURING a game based on changing circumstances. This system allows these post-mod load edits to take place. Again, it was primarily developed for hinging on Game Options so that rather than requiring a player to determine what modules they wanted active or not by manipulating key documents within our mod's file structure before loading, an option could be developed to hinge these adjustments on that could at least be determined on game setup. Much easier from a player perspective.
Creating a Replacement Object: Step I
Ok, so how, as modders, do we create a Replacement object entry?
I'll use ls612's first replacement entry for an example. Right at the beginning of the entry there's a few things to note:
Code:
<TraitInfo>
<Type>TRAIT_PHILOSOPHICAL</Type>
<ReplacementID>TRAIT_LS612_PHILOSOPHICAL</ReplacementID>The <ReplacementID> tag act's like a second primary key. I like to think of it as the Object's Last Name. If no two people may be named the same and we only ever had first names like "Jim" or "Bob" then the way we can see it is that up till now we've never had 'last names'. But now we do and it's the <ReplacementID> tag.
Of course, all those who were never given last names have a default of NO last name but if an object has been given a 'last name' or rather, a <ReplacementID> tag, then it's an object that doesn't have an independent existence from the original and will only come into play IF the conditions that are set for the replacement to take place become true.
So the original Philosophical trait entry may be considered 'Bob' while the replacement, 'Bob ls612'.
Data-wise, the game has loaded the replacement entry as if it is a completely new object but knows to only put it into play over the top of the original if the boolean expression condition is true... this is one reason that we should not use this with too great a frequency. It can end up being a lot of data the game has loaded and is maintaining. This is not to say we should never use it of course. It has its uses!
Now... WHAT the name IS is relatively unimportant but there should be a continuity within a given set. For example, ls612's focused trait entries are all named starting with TRAIT_LS612_ and ending with the primary name block of the original that is replaced (in this example: PHILOSOPHICAL since that's what's being replaced.) Additionally, no two objects should ever be given the same first (<Type>) AND last (<ReplacementID>) names!
Creating a Replacement Object: Step II
So the second and last step to setting up a replacement is at the END of the replacement entry (I'll use the same ls612 object as an example):
Code:
<ReplacementCondition>
<Has>
<GOMType>GOM_OPTION</GOMType>
<ID>GAMEOPTION_LS612_TRAITS</ID>
</Has>
</ReplacementCondition>
</TraitInfo>But again, this simple example of a ReplacementCondition tag use is a display of it's primary use both from a requested function capacity perspective and from the angle of how it's been applied so far. This is how we hinge the replacement to take place on a game option being active. If you've guessed, the Focused Traits game option is designated as GAMEOPTION_LS612_TRAITS.
Wrapup
(SO, since I've written this for you in the short term, to be very specific, I named the game option shell I established for you GAMEOPTION_NIGHTMARE_MODE. So all you'd do is include the ReplacementCondition tag at the very end just as it's shown here in the example and replace the reference to GAMEOPTION_LS612_TRAITS with GAMEOPTION_NIGHTMARE_MODE. Once all your new difficulty definitions are made to be replacements of the originals according to this mechanism, you'll just have to turn on the visibility on the option in the GameOptionInfos.xml.)
Keep in mind that this mechanism is subject to some adjustment to how it works in the future so that we don't have to FULLY re-write EVERY tag used on the original entry. But at the moment, keep in mind, you must write this entry exactly as if it is a completely new object - it will NOT currently inherit any default values from the original as the WoC modular edit system will. I think once Alberts2 and I have sorted out how the copy non defaults tags are supposed to be setup on all tags in the infos files we will be better setup to work on making the replacement mechanism work in a similar manner.
Also... it does NOT matter if a replacement is placed in a module or in the core. However, the core AND replacements ARE subject to WoC editing. If you wanted to adjust the use of a given tag on a replacement entry, you'd simply treat that object just as if it were any other (but you'd need to include the ReplacementID tag to let the system know you're editing the replacement and not the core.)
In summary... the replacement mechanism is simple, powerful, and effective. It lends us enormous as of yet untapped potential! I sometimes think we haven't even scratched the surface of how much can be achieved with this given that we've limited ourselves to only option edits so far...
Hopefully this is clear, helpful and concise. Any questions?
