A Modders Guide to Beyond the Sword About the authors:Kael- Lead designer of the Beyond the Sword scenario Fall from Heaven: Age of Ice Impaler[WrG]- Lead designer and programmer of the Unit Art Styles and Modular XML features of BtS, Team Leader of the CCCP (Civ4 Community Core Project) Solver- Design Consultant and programming contributor for Beyond the Sword We’ve read articles describing the new game play that is coming in Beyond the Sword (BtS), and tantalizing hints about what it will offer. This article was written to detail some of the new features of BtS that may not mean much to the average player, but will be important to mod makers. Disclaimer: Until BtS ships nothing is locked down. Everything in here is subject to change. Anything that is or isn’t in BtS as it is recorded here may be due to last minute changes or my own mistakes in documenting. Table of Contents 1.0[tab]Less Grunt Work [tab]1.1[tab]CIV4FormationInfos.xml [tab]1.2[tab]CIV4CityLSystem.xml 2.0[tab]Modular XML 3.0[tab]Unit Art Styles [tab]3.1[tab]Step 1: CIV4Civilizations.xml [tab]3.2[tab]Step 2: CIV4UnitArtStyleInfos.xml [tab]3.3[tab]Step 3: CIV4ArtDefines_Unit.xml 4.0[tab]Mod Specific Interface 5.0[tab]New python functions [tab]5.1[tab]CvEventManager.py [tab]5.2[tab]CvGameUtils.py 6.0[tab]Help Attribute 7.0[tab]Promotions can change the look of models 8.0[tab]Events 9.0[tab]The Python Callback Defines file 10.0[tab]New Attributes [tab]10.1[tab]Units [tab]10.2[tab]Promotions [tab]10.3[tab]Buildings [tab]10.4[tab]LeaderHeads [tab]10.5[tab]Technologies [tab]10.6[tab]Features [tab]10.7[tab]Improvements 11.0[tab]New Game Parameters [tab]11.1[tab]New Global Defines [tab]11.2[tab]New ini options 12.0[tab]What can you do now? 13.0[tab]Converting to Beyond the Sword 14.0[tab]Appendix A- Modular XML Loading [tab]14.1[tab]Introduction [tab]14.2[tab]Making Modules [tab]14.3[tab]How it Works [tab]14.4[tab]What Doesn’t Work [tab]14.5[tab]Naming Rules [tab]14.6[tab]Supported File Types [tab]14.7[tab]Schema [tab]14.8[tab]Organization [tab]14.9[tab]Troubleshooting [tab]14.10[tab]Cache Loading [tab]14.11[tab]Templates [tab]14.12[tab]Resources 15.0[tab]Appendix B- Event Guide [tab]15.1[tab]CIV4EventInos.xml [tab]15.2[tab]CIV4EventTriggers.xml [tab]15.3[tab]Python and Events [tab]15.4[tab]EventTriggeredData [tab]15.5[tab]Creating Events 16.0[tab]Appendix C- Links 1.0[tab]Less Grunt Work First off, two things BtS removes. Mod makers are very familiar with the Civ4FormationInfos.xml and Civ4CityLSystem.xml files. In vanilla Civ4 and Warlords, units added to the game have to be added to the formations file, and any building you want to show up in the city has to be added to the CityLSystem file. BtS does away with the need to update these files with each new entry. 1.1[tab]CIV4FormationInfos.xml Instead the formation file includes formation types. Then when you create a new unit you define its formation type (ex: FORMATION_TYPE_ANIMAL) and it uses that definition for formations with that unit instead of having to be defined per unit. So the following would be an attribute of a unit in the CIV4UnitInfos.xml file: <FormationType>FORMATION_TYPE_DEFAULT</FormationType> I’ll include a copy of one of the definitions of a formation file here. But in general modders won’t need to ever touch it again. Personally, I modified mine to add some larger groups than the default. But even in this it was easier than in Vanilla or Warlords because I just created the new formation and assigned it to FORMATION_TYPE_DEFAULT (or whatever formation type I wanted to use) and all the units began using it. Code: <UnitFormation> <Name>IDLE (1)</Name> <FormationType>FORMATION_TYPE_DEFAULT</FormationType> <EventMaskList> <EventType>ENTITY_EVENT_IDLE</EventType> <EventType>ENTITY_EVENT_SURRENDER</EventType> <EventType>ENTITY_EVENT_CAPTURED</EventType> <EventType>ENTITY_EVENT_GREAT_EVENT</EventType> <EventType>ENTITY_EVENT_FOUND</EventType> <EventType>ENTITY_EVENT_BUILD</EventType> <EventType>ENTITY_EVENT_PARADROP</EventType> <EventType>ENTITY_EVENT_SHOVEL</EventType> <EventType>ENTITY_EVENT_DIE_ANIMATION</EventType> </EventMaskList> <UnitEntry> <UnitEntryType>UNIT</UnitEntryType> <Position> <x>-0.0201342281879</x> <y>-0.201342281879</y> </Position> <PositionRadius>13.0384048104</PositionRadius> <Direction>3.14159265359</Direction> <DirVariation>0.188679622641</DirVariation> </UnitEntry> <UnitEntry> <UnitEntryType>GENERAL</UnitEntryType> <Position> <x>-0.332214765101</x> <y>0.694630872483</y> </Position> <PositionRadius>22.0</PositionRadius> <Direction>3.11129889367</Direction> <DirVariation>0.440454310911</DirVariation> </UnitEntry> <UnitEntry> <UnitEntryType>SIEGE</UnitEntryType> <Position> <x>-0.573825503356</x> <y>-0.53355704698</y> </Position> <PositionRadius>25.0</PositionRadius> <Direction>2.44685437739</Direction> <DirVariation>0.521536192416</DirVariation> </UnitEntry> </UnitFormation> 1.2[tab]CIV4CityLSystem.xml Likewise the LSystem size of a building is set in its art definition (ex: LSYSTEM_3x2) instead of having to define every building in the LSystem file. Code: <BuildingArtInfo> <Type>ART_DEF_BUILDING_PALACE</Type> <LSystem>LSYSTEM_3x2</LSystem> <bAnimated>0</bAnimated> <fScale>1.15</fScale> <fInterfaceScale>0.43</fInterfaceScale> <NIF>Art/Structures/Buildings/Palace/Palace.nif</NIF> <KFM/> <Button>,Art/Interface/Buttons/Buildings/Palace.dds,Art/Interface/Buttons/Buildings_Atlas.dds,6,5</Button> </BuildingArtInfo> That’s it. The game takes care of the rest. 2.0[tab]Modular XML Ever wanted to add a new unit to a mod without touching any of the original files? Or wanted to add new objects to an existing mod, but then the base mod changes and you have to redo your work? Modular XML allows the game to load several different XML files as a single file. With it you can add a new unit, unit class and unit art file that only contains the data for your new unit. Then if the base mod changes it won’t effect your files and you don’t have to re-update your changes. This is even more promising when considering the ability to merge XML mods. You could take 3 different mods that each introduce a new civilization, unique units and buildings and play them together by just copying them into the appropriate directory. No need to merge code and if the makers of those mods update their files it’s easy enough to reapply without affecting everything else in your game. For more details on Modular XML, check out Appendix A of this guide. 3.0[tab]Unit Art Styles There has been a lot of amazing work done creating new unit art for civilization 4. Many of these units have been implemented as “flavor” units, sharing identical stats but added to the game to vary the artwork of different civilizations. Unfortunately this requires a new unit to be added to the game, a swordsman (for example) that is a duplicate in every way except its art definition. BtS allows us to define unit art types, similar to the building art types in warlords. With it you can have one unit definition but configure different civilizations to use different art for that unit. So the Greek scout can be made to look different than an Aztec scout without adding a new unit to the game. There are 3 steps required to enable this. 3.1 Step 1: CIV4CivilizationsInfos.xml In this file we need to define the civilizations Unit Art Style as follows: Code: <CivilizationInfo> <Type>CIVILIZATION_AMERICA</Type> <Description>TXT_KEY_CIV_AMERICA_DESC</Description> <ShortDescription>TXT_KEY_CIV_AMERICA_SHORT_DESC</ShortDescription> <Adjective>TXT_KEY_CIV_AMERICA_ADJECTIVE</Adjective> <Civilopedia>TXT_KEY_CIV_AMERICA_PEDIA</Civilopedia> <DefaultPlayerColor>PLAYERCOLOR_BLUE</DefaultPlayerColor> <ArtDefineTag>ART_DEF_CIVILIZATION_AMERICA</ArtDefineTag> <ArtStyleType>ARTSTYLE_EUROPEAN</ArtStyleType> [b]<UnitArtStyleType>UNIT_ARTSTYLE_EUROPEAN</UnitArtStyleType>[/b] This is very similar to the way city art styles were defined in warlords but added as a separate attribute so modders can use different unit and city building styles. A NONE value will cause the Civ to use all default Unit Art. 3.2[tab]Step 2: CIV4UnitArtStyleTypeInfos.xml This is a new XML file in BtS. It contains the definition for the Unit Art Style and allows a new unit art meshes to be used for a given unit. In the example below the ART_DEF_UNIT_ARCHER_EURASIAN is the Early art definition used for an Archer and ART_DEF_UNIT_ARCHER_EUROPEAN is used in the middle and late periods. The Archer like most units has only one UnitMesh as specified on its CIV4UnitInfos.xml element. But units can actually have any number of Meshes, the Settler units are the only Original game units to use more then one Mesh and to modify these simply list the replacement Meshes as <UnitMeshGroup> elements, they will be matched in the order with the CIV4UnitInfos meshes and replace it one for one, any number of Meshes can be present in a Unit and all can be substituted in this way. Any Unit not given replacements for a StyleType will simply be defaulted to the Art from the UnitInfos.xml file and any individual ARTDEFs can be referenced any number of times and in as many different StyleTypes as desired allowing considerable sharing and creation of Styles which differ only at certain time periods to reflect cultures branching and merging. Code: <UnitArtStyleTypeInfo> <Type>UNIT_ARTSTYLE_EUROPEAN</Type> <StyleUnits> <StyleUnit> <UnitType>UNIT_ARCHER</UnitType> <UnitMeshGroup> <EarlyArtDefineTag>ART_DEF_UNIT_ARCHER_EURASIAN</EarlyArtDefineTag> <LateArtDefineTag>ART_DEF_UNIT_ARCHER_EUROPEAN</LateArtDefineTag> <MiddleArtDefineTag> ART_DEF_UNIT_ARCHER_EUROPEAN </MiddleArtDefineTag> </UnitMeshGroup> </StyleUnit> <StyleUnit> <UnitType>UNIT_SETTLER</UnitType> <UnitMeshGroup> <EarlyArtDefineTag>ART_DEF_SETTLER_MALE_EUROPEAN</EarlyArtDefineTag> <LateArtDefineTag> ART_DEF_SETTLER_MALE_EUROPEAN </LateArtDefineTag> <MiddleArtDefineTag> ART_DEF_SETTLER_MALE_EUROPEAN </MiddleArtDefineTag> </UnitMeshGroup> <UnitMeshGroup> <EarlyArtDefineTag>ART_DEF_SETTLER_FEMALE </EarlyArtDefineTag> <LateArtDefineTag>ART_DEF_SETTLER_FEMALE </LateArtDefineTag> <MiddleArtDefineTag>ART_DEF_SETTLER_FEMALE </MiddleArtDefineTag> </UnitMeshGroup> </StyleUnit> </StyleUnits> </UnitArtStyleTypeInfo> 3.3[tab]Step 3: CIV4ArtDefines_Unit.xml Just as in Civ4 the Unit Art Information has to exist for the unit. But instead of using the default one assigned to that unit in the Civ4UnitInfos.xml (ART_DEF_UNIT_ARCHER for example) Unit Art Styles allowed us to use a alternate one such as this: Code: <UnitArtInfo> <Type>ART_DEF_UNIT_ARCHER_EUROPEAN</Type> <Button>,Art/Interface/Buttons/Units/Archer.dds,Art/Interface/Buttons/Unit_Resource_Atlas.dds,4,1</Button> <fScale>0.44</fScale> <fInterfaceScale>1.0</fInterfaceScale> <bActAsLand>0</bActAsLand> <bActAsAir>0</bActAsAir> <NIF>Art/Units/Archer_European/Archer_European.nif</NIF> <KFM>Art/Units/Archer_European/Archer.kfm</KFM> <SHADERNIF>Art/Units/Archer_European/Archer_European_fx.nif</SHADERNIF> <ShadowDef> <ShadowNIF>Art/Units/01_UnitShadows/UnitShadow.nif</ShadowNIF> <ShadowAttachNode>BIP Pelvis</ShadowAttachNode> <fShadowScale>0.85</fShadowScale> </ShadowDef> <fBattleDistance>0.35</fBattleDistance> <fRangedDeathTime>0.31</fRangedDeathTime> <bActAsRanged>1</bActAsRanged> <TrainSound>AS2D_UNIT_BUILD_UNIT</TrainSound> <AudioRunSounds> <AudioRunTypeLoop/> <AudioRunTypeEnd/> </AudioRunSounds> </UnitArtInfo> Note that the unit button graphic is defined on the UnitArtInfo, it is no longer set in the CIV4UnitInfos.xml file. This allows us to use different buttons for different unit art styles. This change will also require modders converting older mods to BtS to move all their button info into the art file. By modifying the SDK you can create alternative types of StyleUnit logic with their own xml files and logic structures such as Units which show different Artwork based on how heavily they are damaged or the presense of specific Promotions. 4.0[tab]Mod Specific Interface Firaxis’ default blue interface is pretty good but isn’t appropriate to all mods. It is possible to change your interface in vanilla Civ4 and Warlords but it is a game setting and isn’t moddable. BtS changes that. Modders can change the color of the interface, fonts, bars, everything to design the interface they want for their mod. First you will need the following entry in your CIV4ArtDefines_Misc.xml file: Code: <MiscArtInfo> <Type>DEFAULT_THEME_NAME</Type> <Path>Mods/[ModName]/Resource/Civ4.thm</Path> <fScale>0.0</fScale> <NIF>None</NIF> <KFM>None</KFM> </MiscArtInfo> Anything in the “..\Sid Meier's Civilization 4\Resource” subdirectory’s can be overwritten by matching files placed in the “..\Sid Meier's Civilization 4\Beyond the Sword\Mods\[ModName]\Resource” container. The Resource container must contain a Civ4.thm file that redirects it to the appropriate mod specific resources as follows: Code: // *** Control Bitmap Theme file // Set the resource resource_path "Mods/[ModName]/Resource"; // Setup common properties include "Mods/[ModName]/Resource/Themes/Civ4/Civ4Theme.thm"; Detailing all the possible options that can be themed is beyond the scope of this document, it is basically everything that can be done with earlier versions, but now these themes can be included with mods instead of being applied to the whole game. If you are interested in creating a theme for your mod you can start now by creating that theme in the vanilla or warlords resource container (make sure to make a backup copy of the original). Then when BtS comes out you can copy it into your mods directory and begin using it. 5.0[tab]New python functions Firaxis has been hard at work adding new python functions, places where we can intercept functions and apply our own logic to keep things from happening (as in disabling units from being able to enter certain plots in unitCannotMoveInto) or modify the actions (such as creating new experience point requirements in getExperienceNeeded). 5.1[tab]CvEventManager.py These python functions don’t inherently make the game better. But they do offer an opportunity for creative modders to do amazing things. With a few lines of python it becomes easy to intercept nuke explosions and warn the world of their use, increase their effect, or even trigger massive post-apocalyptic effects. plotFeatureRemoved- Passed the plot, the feature that was removed and the city (if the plot was a city) plotPicked- ? not called from the SDK nukeExplosion- Passed the plot and the unit that caused the explosion gotoPlotSet- ? not called from the SDK cityHurry- Called whenever a production is hurried in a city unitSpreadReligionAttempt- Passed the unit, the attempted religion and if it was successful or not UnitGifted- Passes the unit, the old owner of the unit and the plot that unit is in unitBuildImprovement- Passed the unit, the improvement type they are building and if it is complete or not corporationFounded- Passed the corporation and the founding player corporationSpread- Passed the corporation, the owning player and the city corporationRemove- Passed the corporation, the owning player and the city playerChangeStateReligion- Passed the player, the new religion and the old religion playerGoldTrade- Passed the player giving the gold, the player receiving and the amount exchanged 5.2[tab]CvGameUtils.py isVictory- Allows a check to see if any player is allowed to achieve victory yet canDeclareWar- To give modders the option to enable/disable war declarations dynamically unitCannotMoveInto- To block moving into plots based on any criteria canBuild- To block the creations of improvements based on any criteria cannotFoundCity- Passed the player and the coordinates of the plot cannotSpreadReligion- To block the ability to spread religions citiesDestroyFeatures- To enable or disable feature destruction when cities are created canFoundCitiesOnWater- To allow cities to be created on water tiles doCombat- To replace the SDK combat function with a python process getConscriptUnitType- To provide the unit type provided through conscription getCityFoundValue- To modify the AI’s preference for city placement canPickPlot- ? not called from the SDK getUnitCostMod- To modify the cost of units dynamically getBuildingCostMod- To modify the cost of buildings dynamically canUpgradeAnywhere- To allow the unit to be upgraded anywhere getWidgetHelp- To add additional text to mouse over help getUpgradePriceOverride- To replace the upgrade price with a new value getExperienceNeeded- To replace the experience system with a different values This is in addition to additional data sent to other python functions. For example, the onUnitMove function now has the old plot passed to it as well. So if you want to perform a python action when a unit leaves his cultural borders that is now easier to do. 6.0[tab]Help Attribute This may seem like a minor thing but it is so effective and easy to use that it deserves special mention. There is a new schema attribute called Help on Traits, Units, Promotions, Terrain, Buildings, Bonuses, Features and Technologies. Help is intended to hold a text string such as TXT_KEY_UNIT_GIANT_DEATH_ROBOT_HELP and anything in that string is displayed in mouse over help text for that object. In earlier versions if modders wanted to add additional help text they would need to modify the SDK. This is so much easier. 7.0[tab]Promotions can change the look of models I am going to apologize beforehand for the lack of detail in this section. I’m not a graphics guy and I haven’t used this feature myself. But I have toyed with some of the units that use it. Basically it is possible to have a model changed based on the promotions it has. For example, you could make a bomber model that, if it has the correct promotion, shows a bomb strapped to its bottom. Then if the promotion is removed, say by a bombing action, the model would be changed so the bomb is no longer visible. The same could be done in showing swords and axes in units hands, armor they are wearing, units surrounded in clouds of putrid gas, radiation, etc. I will stress that this isn’t as simple as making a promotion, pointing it to model art and having everything work. The model has to be made with the “attachment” built into it. By default it isn’t displayed, but with the promotion it shows up. So it will be significant modeling work to use this function, but I have no doubt the amazing artists here at CivFanatcis will have a lot of fun with this feature. 8.0[tab]Events Random events are one of the new features in Civ4: Beyond the Sword. The game ships with over 150 events, which vary from happiness and diplomatic bonuses to free promotions and technological breakthroughs. The event system provides a great foundation for modders to build open, as all events can be modded and new ones can be added. You can create a wide array of possible events through XML modding only, but events can also be enhanced by Python for more versatility. Appendix B of this guide has some examples of events that can be modded in. The events described therein, along with some others, can be found in an event mod created by Solver. Think of the mod as an addendum to this guide, if you will. It can be found at (mod will linked after BtS releases). It’s important to understand the two basic building blocks of the event system; triggers and events. “Triggers” are a collection of parameters indicating conditions when they can activate. Triggers check whether you have the required technologies, population, etc. If the trigger’s conditions are met, it has a chance of activating. When a trigger is activated, it gives the player choice between one or more “events” (well, when there is only one event, there’s no choice). Events themselves are what provides the specific results that then affect the player. Players may be inclined to think of the event system as consisting of “events” and “choices” – that’s not really accurate. Every choice is a separate event, and a trigger is what gives those choices. As most other things in Civ4, events are primarily handled in the SDK. Events are described by the CvEventInfo class, which mimics the XML description of events. Appendix B has a description of event tags in the XML file. If you can read C++, you may want to take a look at the definition of CvEventInfo. The correspondence between member functions of that class and the XML values should be fairly obvious. Event triggers are kept in Civ4EventTriggerInfos.xml and that file, along with triggers in general, will be described after the event description explanations. For more details on events, check out the Event Guide in Appendix B. 9.0[tab]The Python Callback Defines file BtS is fast. One of the things Firaxis did to speed up the game was implement a PythonCallbackDefines.xml file. That file has entries for many CPU intensive python functions such as the following: Code: <Define> <DefineName>USE_CANNOT_FOUND_CITY_CALLBACK</DefineName> <iDefineIntVal>0</iDefineIntVal> </Define> By default (as configured above) the Found City python routine will never be called. If you want to use that function in your mod you will need to include a modded copy of the PythonCallbackDefines.xml with the iDefineIntVal set to 1 to enable that python callback. The following python functions are disabled by default: USE_CANNOT_FOUND_CITY_CALLBACK USE_CAN_FOUND_CITIES_ON_WATER_CALLBACK USE_IS_PLAYER_RESEARCH_CALLBACK USE_CAN_RESEARCH_CALLBACK USE_CANNOT_DO_CIVIC_CALLBACK USE_CAN_DO_CIVIC_CALLBACK USE_CANNOT_CONSTRUCT_CALLBACK USE_CAN_CONSTRUCT_CALLBACK USE_CAN_DECLARE_WAR_CALLBACK USE_CANNOT_RESEARCH_CALLBACK USE_GET_UNIT_COST_MOD_CALLBACK USE_GET_BUILDING_COST_MOD_CALLBACK USE_GET_CITY_FOUND_VALUE_CALLBACK USE_CANNOT_HANDLE_ACTION_CALLBACK USE_CAN_BUILD_CALLBACK USE_CANNOT_TRAIN_CALLBACK USE_CAN_TRAIN_CALLBACK USE_UNIT_CANNOT_MOVE_INTO_CALLBACK USE_CANNOT_SPREAD_RELIGION_CALLBACK USE_FINISH_TEXT_CALLBACK USE_ON_UNIT_SET_XY_CALLBACK USE_ON_UNIT_SELECTED_CALLBACK USE_ON_UPDATE_CALLBACK USE_ON_UNIT_CREATED_CALLBACK USE_ON_UNIT_LOST_CALLBACK Keep in mind that these python functions were selected because they called frequently enough to constitute a significant processor cost if they are enabled. So if you will be enabling them for use in your mod expect that slower computers may suffer a performance hit.