Modding Guide Part 1: UPResolutionDefs.xml, ColonizeEventDefs.xml, GalacticEventDefs.xml, & IdeologicalGalacticEventDefs.xml

from GalCiv3 Forums

I started a thread last week where I listed all (just about) the XML files and detail (or vague guesses) on their function with the intent of eventually coming along and adding new threads for individual files where I go into some details on how to mod them to include new stuff.

The last few days, I've been giving a lot of thought about what to write a guide for first.. Finally It's come down to this grouping simply because they make a good low key first step for a would be modder.  While trying to decide the best way to extend the tech tree/shipcomponents/add new hulls/etc might seem exciting to announce the results, balancing them to be fun & interesting across a wide range can be more involved from planning to testing & final implementation.  a new event/UP Resolution however is much less involved with quite a bit more room for non-technical creativity to dip one's toes into the murk with.

Basics 

These guys are as basic and obvious as basic & obvious can get.... Have some great idea(s) for stuff that can/should be added to the colonization events?... Here's your target!

At the top of an XML file is the scema/encoding/etc, mostly ignore everything before these two lines

<!-- Created with the Gal Civ 3 Editor -->
<!-- ColonizeEventDefs.xml -->

Playing above them could cause havoc & nothing interesting is there.  The <!-- comment text goes here --> block is how you can add a comment for human readers to comment [label/describe] things you want to comment.  There is one important detail there however:

<GameEventList .... stuff> then at the very tail end is </GameEventList>.  Everything between those two tags should be game events.  If you were to go digging right now into  ColonizeEventDefs.xml, GalacticEventDefs.xml, -OR- IdeologicalGalacticEventDefs.xml... you would notice they are all the same!  That sameness makes them an excellent intro to xml since it does a good job of showing how it's the coding equivalent of legos $ 

 

 ColonizeEventDefs.xml, GalacticEventDefs.xml, & IdeologicalGalacticEventDefs.xml


All Three of these files are essentially the same with very minor differences Lets start with the very first colonization event (it only looks complicated)... Despite appearances, it's pretty Simple:

  • <GameEvent>
    • This is the opening tag for the specific GameEvent with a </GameEvent> Later to signify the end of this particular event.  
      • If you notice, tags are often indented to give The appearance of being nested within the parent... That's because it makes the results far more readable to a human.  XML interpreters rarely care about it much however if you use a different intent style.
  • <InternalName>PodsEvent</InternalName>
    • What the heck is an internal name & PodsEvent?  How do you know that you might be asking... Buuut  if you go look in GalCivIII\data\English\Text\ColonizeEventText.xml, on the 11th line down you will see "<Label>PodsEvent_Name</Label>"... In fact, go do that now before moving on.  When you do that, you will notice the text to the actual pods event along with mamy of the potentially "wtf?? inducing labels.  Once upon a time, games might have had a cryptic series of gibberish where modding this type of thing would have needed a table of stuff if it was possibile at all
       
    • <DisplayName>PodsEvent_Name</DisplayName>
    • <Description>PodsEvent_Dec</Description>
    • <WindowTitle>PodsEvent_Title</WindowTitle>
    • <ArtDefine>Colonizing_Event_Ruins.png</ArtDefine>
    • <Type>ColonizeEvent</Type>
      • This is the next interesting spot in the code.  Sure writing up the text for new events in ColonizeEventText.xml might be a lot of fun... If you are reading this, you probably want to know how to set the bonus's to match up with your new events!  I'm getting there, but this tag is important
      • The other possibility is  <Type>GalacticEvent</Type>. There may even be more, but this specifies if the GameEvent is a colonization event or a GalacticEvent
    • <Weight>25</Weight>
      • I'kk be honest here!  I don't know what this does, but... we can guess! Lets look at other GameEvents & see what they have set... Well in this case, every single colonization Event is 25 & every single IdeologicalGelacticEvent is 50 for weight... I'm going to go out on a limb & say "leave this where it is or unpredicatable results might occur".  if some events had a higher/lower weight than others, I'd expect that those events were more or less likely to show up over others on the other end of the spectrum though.
    • <Choice>
      • OOOH... the xml says It's starting a choice
    • <Type>Benevolent</Type>
    • <Description>PodsEvent_Benevolent_Bonus_Name</Description>
    • <BonusDescription>PodsEvent_Benevolent_Bonus_Dec</BonusDescription>
    • <Trigger>
  • <OnEvent>OnEventChoice</OnEvent>
    • This section is going to define what happens when you make a choice.  
      • It looks like instant is currently our only option, maybe there will be options after so many turns, a certain population, while at war/peace, etc later..  For now,, use this one!
  • <Target>
  • <TargetType>Faction</TargetType>
  • </Target>
    • It looks like TargetType are Faction, Planet, Colony, Or starbase are the various options.  The best way to decide which is right is to find an event with a target like you want & copy that as a starting point! 
  • <Lifetime>Instant</Lifetime>
    • The Other Option appears to be Target.  What's the difference?... no idea, give both a try & see which is better for your idea :).  If you get stuck, start a thread on it with your observations & see who comes along to help.
    • <Modifier>
  • <EffectType>CultureBenevolent</EffectType>
    • This one might not look very exciting since it's describing an effect that simply consists of +10 benevolent points, but if you look down to the neutral choice, it gives +10 neutral points and a 0.25  +25% bonus/-25% penalty  Multiplier to to research on that colony.  Want to know some other options?... look at the other Game event options listed & find the bonus's that line up well with your prospectiveGameEvent
    • <Target>
  • <TargetType>Faction</TargetType>
  • </Target>
  • <BonusType>Flat</BonusType>
    • This is the next interesting tag, The other option isa Multiplier.  While flat simply adds that much, a multiplier adds a value determined by what the base is then adds/subtracts the result to/from the base.  Sometimes, replacing a traditionally flat bonus with a Multiplier (or vice versa) can yield interesting results, sometimes it will yield little more than an error (or crash), but that's no reason not to try it when it seems like a good/interesting idea!


<Value>10</Value>
</Modifier>
</Trigger>
</Choice>

    • And now it ends the first (benevolent) choice to start a new (neutral) one below

<Choice>
<Type>Neutral</Type>
<Description>PodsEvent_Neutral_Bonus_Name</Description>
<BonusDescription>PodsEvent_Neutral_Bonus_Dec</BonusDescription>
<Trigger>
<OnEvent>OnEventChoice</OnEvent>

<Target>
<TargetType>Faction</TargetType>
</Target>
<Lifetime>Instant</Lifetime>
<Modifier>
<EffectType>CultureNeutral</EffectType>
<Target>
<TargetType>Faction</TargetType>
</Target>
<BonusType>Flat</BonusType>
<Value>10</Value>
</Modifier>
</Trigger>
<Trigger>
<OnEvent>OnEventChoice</OnEvent>
<Target>
<TargetType>Planet</TargetType>
</Target>
<Lifetime>Target</Lifetime>
<Modifier>
<EffectType>Research</EffectType>
<Target>
<TargetType>Colony</TargetType>
</Target>
<BonusType>Multiplier</BonusType>
<Value>0.25</Value>
</Modifier>
</Trigger>
</Choice>
<Choice>
<Type>Merciless</Type>
<Description>PodsEvent_Merciless_Bonus_Name</Description>
<BonusDescription>PodsEvent_Merciless_Bonus_Dec</BonusDescription>
<Trigger>
<OnEvent>OnEventChoice</OnEvent>
<Target>
<TargetType>Faction</TargetType>
</Target>
<Lifetime>Instant</Lifetime>
<Modifier>
<EffectType>CultureMerciless</EffectType>
<Target>
<TargetType>Faction</TargetType>
</Target>
<BonusType>Flat</BonusType>
<Value>10</Value>
</Modifier>
</Trigger>
<Trigger>
<OnEvent>OnEventChoice</OnEvent>
<Target>
<TargetType>Planet</TargetType>
</Target>
<Lifetime>Target</Lifetime>
<Modifier>
<EffectType>Research</EffectType>
<Target>
<TargetType>Colony</TargetType>
</Target>
<BonusType>Multiplier</BonusType>
<Value>0.5</Value>
</Modifier>
</Trigger>
</Choice>
</GameEvent>

 

Right now I don't think there are any events with more than three choices (or more than 1 of the same ideology), but it stands to reason that making one with four or more will either display the first three, give a scroll thingy to the options...  or crash the game, but I suspect that last one unlikely  I don't know what would happen if you had 2-3 of the same ideology type, but I suspect the result would be exactly as the code grants regardless of if it displays the choices unexpected colors.

The best way to go about modding things is to start by copying one that's similar & making changes to it rather than trying to hope you remember all the required bits

 

 

UPResolutionDefs.xml

Since three of the four files are the same sort of formatting, lets jump over to UPResolutions.xml

Once again, this is a two part file (imagine how unwieldy it would be all in one file!).  The first is GalCivIII\data\Game\UPResolutionDefs.xml where the mechanical bits & bobs are stored.  The second is Ga,civIII\Data\English\Text\UP ResolutionDefsText.xml, the split is the same sort of thing as above where the "fluff" is in one file & the mechanics in a second.These are much simpler, I was not expecting the colonization events would make such long mechanical entries, but seeing just how flexible they are gives me quite a bit of curiosity since I vaguely recall them being quite a bit more restrictive in GalCivII, That change looks like a great improvement.  It would be interesting if we could create race specific event files! *hint hint*...

Lets start with the first UP Resolution


<UPResolution>
<InternalName>ElectChairmanRes</InternalName>
<DisplayName>ElectChairmanRes_Name</DisplayName>
<Description>ElectChairmanRes_Dec</Description>
<Question>ElectChairmanRes_Question</Question>
<VoteType>
<VoteType>PickFaction</VoteType>
</VoteType>
<TurnDuration>104</TurnDuration>
</UPResolution>

Okay, Bad choice... chairman is sort of a hard coded thing

Lets look at a xoouple more instead....


<UPResolution>
<InternalName>UnitedPlanetsHeadquarters</InternalName>
<DisplayName>UnitedPlanetsHeadquarters_Name</DisplayName>
<Description>UnitedPlanetsHeadquarters_Dec</Description>
<Question>UnitedPlanetsHeadquarters_Question</Question>
<VoteType>
<VoteType>PickFaction</VoteType>
</VoteType>
<Behavior>UnitedPlanetsHQ</Behavior>
<TurnDuration>104</TurnDuration>
<MeetingCooldownAfter>3</MeetingCooldownAfter>
<Modifier>
<EffectType>CreditsPerTurn</EffectType>
<Scope>UPResolutionGalaxy</Scope>
<Target>
<TargetType>Faction</TargetType>
</Target>
<BonusType>Multiplier</BonusType>
<Value>-0.01</Value>
</Modifier>
<Modifier>
<EffectType>Influence</EffectType>
<Scope>Global</Scope>
<Target>
<TargetType>Colony</TargetType>
</Target>
<BonusType>Multiplier</BonusType>
<Value>0.5</Value>
</Modifier>
</UPResolution>


<InternalName>UnitedPlanetsTourismBoard</InternalName>
<DisplayName>UnitedPlanetsTourismBoard_Name</DisplayName>
<Description>UnitedPlanetsTourismBoard_Dec</Description>
<Question>UnitedPlanetsTourismBoard_Question</Question>
<VoteType>
<VoteType>YesNo</VoteType>
</VoteType>
<PersonalityTraitModifier>
<PersonalityTrait>Expansionist</PersonalityTrait>
<VoteInfluence>10</VoteInfluence>
</PersonalityTraitModifier>
<PersonalityTraitModifier>
<PersonalityTrait>Xenophobic</PersonalityTrait>
<VoteInfluence>-10</VoteInfluence>
</PersonalityTraitModifier>
<MeetingCooldownAfter>10</MeetingCooldownAfter>
<Modifier>
<EffectType>CreditsPerTurn</EffectType>
<Scope>UPResolutionGalaxy</Scope>
<Target>
<TargetType>Faction</TargetType>
</Target>
<BonusType>Multiplier</BonusType>
<Value>-0.02</Value>
</Modifier>
<Modifier>
<EffectType>Tourism</EffectType>
<Scope>UPResolutionGalaxy</Scope>
<Target>
<TargetType>Colony</TargetType>
</Target>
<BonusType>Multiplier</BonusType>
<Value>1</Value>
</Modifier>


<UPResolution>
<InternalName>InterstellarTradeStimulusAct</InternalName>
<DisplayName>InterstellarTradeStimulusAct_Name</DisplayName>
<Description>InterstellarTradeStimulusAct_Dec</Description>
<Question>InterstellarTradeStimulusAct_Question</Question>
<VoteType>
<VoteType>YesNo</VoteType>
</VoteType>
<PersonalityTraitModifier>
<PersonalityTrait>Trader</PersonalityTrait>
<VoteInfluence>10</VoteInfluence>
</PersonalityTraitModifier>
<PersonalityTraitModifier>
<PersonalityTrait>Xenophobic</PersonalityTrait>
<VoteInfluence>-10</VoteInfluence>
</PersonalityTraitModifier>
<Modifier>
<EffectType>CreditsPerTurn</EffectType>
<Scope>UPResolutionGalaxy</Scope>
<Target>
<TargetType>Faction</TargetType>
</Target>
<BonusType>Multiplier</BonusType>
<Value>-0.03</Value>
</Modifier>
<Modifier>
<EffectType>TradeLicensesMax</EffectType>
<Scope>UPResolutionGalaxy</Scope>
<Target>
<TargetType>Faction</TargetType>
</Target>
<BonusType>Flat</BonusType>
<Value>2</Value>
</Modifier>
</UPResolution>

<

 

In the three you see the different types of votes (YesNo/PickFaction), duration differences.  Those with a duration have a number of rounds they remain in effect  Those with no duration, last until repealed.  You also get to see them giving wildly different types of bonuses, credits per turn, trade licenses max, influence per turn.  You get to see how different faction traits affect voting patterns (these are configured on a race by race basis in galcivIII\data\game\FactionDefs.xml).  Sadly I'm unable to find an XMl file that defines things like "UPResolutionRedistributeWealth" & some of the other hard coded <action>'s in UPResolutionDefs.xml. I suspect that modders could have a blast building new & more involved/complicated/specialized diplomatic options if the file were opened up to us in time... That right there is part of why I chose to start with these files ;) Truth be told, another part is the number of colonization events that mention biological/non-syntheticRace things (any that do) while not a single one is tailored towards synthetic race(s) In Galactic /Civilizations III Synthetic Empires ;).  Since modding ship parts & planetary structures is still close ebnough to where GalcivII Tutorials will get you started, I went with these :)

16,004 views 10 replies
Reply #1 from GalCiv3 Forums Top

 

  •  A number of the hopefully encouraging predictions I made in the first post were tested by markmid down a few posts & a great deal of good info is included in them for people just coming across the thread.  I encourage you to read on, modding threads are often chock full of good info in the cross discussion of knowledge sharing, this one is no exception

This space reserved for potential future use

Reply #2 from GalCiv3 Forums Top

I must admit i've been holding off modding again, just because things might well change and break as we get closer to release (like some ship designs), but I have decided to have a look again, mostly down to you putting these together.

Again thank you Tetra for taking the time to share your experience and help start foster the modding community, which needs these guides to really get started.

 

If any mod wants to delete this post that would help keep things in the guide more condensed, thank you.

CursorFX - Customize your Windows cursor
Reply #3 from GalCiv3 Forums Top

I started with these files because they seemed the least likely to undergo significant changes.  Shipdefs/imptovements/etc are probably more common mid targets, but almost certain to be getting more changes

Reply #4 from GalCiv3 Forums Top

Testing - I will keep these posts Updated with new info and condense the info I do find over time, feel free to add any into any guides you do, in your words or mine.

Last Update 7/1/15


Testing Contents:

1st Post
Modding Creative Mode
Event Picture Resolution Testing
BK2 Movie Files work in events
Vanilla Directory Sizes.


2nd Post
Modding Tools
Possible Modding Conventions 

3rd Post
Custom Event Testing
4th Choice Testing
Capital Letters needed for label syntax.
Errors By Line
 


Modding Creative Mode 

For anyone modding, you can set the AI to all be on your team and no victory conditions, so you can test your mod (or design ships for races) in peace without the game ending, I am really happy they left this type of creative testing mode in, and hope it stays. You can also make use of the AI to get all the tech researched up quickly for example via trading to test everything you put in.


Event Picture Resolution 

After testing a dozen pictures, all ratios appear to work so far, I have yet to find one that doesn't but please let me know if you do, and what ratio your monitor is.


Further testing the event will fire without a picture at all, even if you put the wrong filename in (which I did, you get a blank image) I wonder if moving picture files will work or other formats, I don't think JPG and animated GIFs work but I am still testing different combinations.


BK2 Movie Files work in events  

So far my tests have allowed me to play game made bk2 files in events! If we can ever encode our own for our custom races etc, you can play movies in your event files. I don't know if any regular BIK files will work but that will be worth a test at some stage (so far no joy), or just other bk2 files to see if we can already make our own. 

  

Vanilla Directory Sizes

You can reduce the resolution of the current pictures if disk space is an issue for you in the future.

Reply #5 from GalCiv3 Forums Top

Modding Tools:

Notepad++ Very handy tool that will allow you to keep track of XML brackets, multiple tabs and go directly to the error line when galciv gives you an error

http://notepad-plus-plus.org/ 

 

Modding Conventions 

For anyone new to modding, using your own two initials from the very start for all your definitions will save people getting any kind of conflicts in the future.


So for example:

 <StringTable>

<Label>PodsEvent_Dec</Label>
<String>Our scouts report that significant portions of the planet are inhabited by a sentient pod-like creature. These pods bond with other sentient life. Those who are bonded by these pods experience significant physical pain at all times, but have heightened intelligence. What are your orders?</String>
</StringTable>


If you were modding it, for best practice you'd use.

<StringTable>
<Label>XA_PodsEvent_Dec</Label>
<String>Our scouts report that significant portions of the planet are inhabited by a sentient pod-like creature. These pods bond with other sentient life. Those who are bonded by these pods experience significant physical pain at all times, but have heightened intelligence. What are your orders?</String>
</StringTable>

 

In this case all your labels would use XA_ before them to prevent conflicts, I am not sure if this will be necessary with the addition of a mod folder and (hopefully) separate files we can drop in to a folder called events for example, to add several event files without having to pick just one, but it's usually good practice when modding any popular game to do this anyway. Unless someone else happens to pick XA you will be fine :), 3 initials makes it even less likely you'll ever have a conflict. 

If we are however limited to one file and copy pasting events into it, this will probably be crucial. 

Reply #6 from GalCiv3 Forums Top

Okay ladies and gents posting again to confirm custom events work A okay! 


Event Testing



Seems thumbnails don't work on these forums so here is the link, or click the picture to enlarge.

http://s4.postimg.org/eckinh3bh/First_Event_Pic.jpg 


I am confirming here that you can delete the vanilla events for total conversions with no visible issues (yet), as this was the only event in my file to test it, currently at weight 25.


Testing two events against each other, weight so far has always worked as you predicted, but I am not sure yet if it's a straight ratio, that will require much more time to deduce. 

 

4th Choice

Adding a 4th choice to an event is not so easy without being able to define another choice type like this:

<Choice>
<Type>Optional</Type> 

Using a second merciless choice brings this up:

C:\Program Files (x86)\Steam\steamapps\common\Galactic Civilizations III/Data/Game\ColonizeEventDefs.xml(217,15): error:
element 'Choice' is not allowed for content model '(InternalName,DisplayName,Description,WindowTitle?,ArtDefine,Type,Special?,Weight,Modifier*,Trigger*,Choice*,Prerequ?)'


Another choice named optional (For testing purposes) brings this up below, the REALLY nice thing is, it breaks the game on launch, so we know immediately, that is very good coding.

C:\Program Files (x86)\Steam\steamapps\common\Galactic Civilizations III/Data/Game\ColonizeEventDefs.xml(168,28): error:
value 'Optional' not in enumeration

C:\Program Files (x86)\Steam\steamapps\common\Galactic Civilizations III/Data/Game\ColonizeEventDefs.xml(217,15): error:
element 'Choice' is not allowed for content model '(InternalName,DisplayName,Description,WindowTitle?,ArtDefine,Type,Special?,Weight,Modifier*,Trigger*,Choice*,Prerequ?)'


Also trying creative things, like putting 2 types in one choice :) but I suspect it's hard coded, unless you can find where it is in the files, I have yet to do so.

 

Capital letters on labels:

Capitals are important when editing the labels, lower case will (most likely) break the game at launch, using a lower case /choice did for me.



Errors by lines:

On further experimentation errors seemed to be referenced by line which is very nice, I think this is always true but I haven't had many errors yet to confirm, just noticed it in the last one I had.

(217,15) - Means line 217 in the referenced file, not sure what the 15 would be in this case. If you are using notepad ++

http://notepad-plus-plus.org/

You can go directly to the line in question for example.

Reply #7 from GalCiv3 Forums Top

Awesome news - Bk2 Files work in events!!!! :)

Going to need a forth post to keep collecting all this data, but yes the game movie files work just fine in place of the png, so far. If we can ever encode our own, then events can have in game movies.


All posts will now be edited, condensed and the first post I've made will keep track of all the event testing I do for you all, as well as when it's updated.

-Reserved-

Reply #8 from GalCiv3 Forums Top

Quoting markmid, reply 4

BK2 Movie Files work in events  

So far my tests have allowed me to play game made bk2 files in events! If we can ever encode our own for our custom races etc, you can play movies in your event files. I don't know if regular BIK files will work but that will be worth a test at some stage, or just other bk2 files to see if we can already make our own. 

  

from here

The best way to learn about Bink is to just try it! Download the RAD Video Tools to compress files into Bink format. Email us to get an evaluation SDK.

Pretty much, it boils down to anyone who has the skills to make a video in a piece of software they know how to use (i.e. maya/poser/etc?), can encode  a bink2 video with relative triviality but making the video would be the hard part.  Of course, that says nothing about using video's you take of physical things, witness the number of "alien" things that are little more than dyed/painted terrestrial objects of mundane origin used in tv  or the varieties of animation used in robot chicken that make very little attempt to not look like something put together last night by an art student when compared to the high end production studio equivalents.... Maybe a visit to a junkyard/home depot, some purple spray paint, paper mache. tin foil, and a little creativity could make that yor event  example a spiffy video :).

Reply #9 from GalCiv3 Forums Top

Quoting Tetrasodium, reply 8



Pretty much, it boils down to anyone who has the skills to make a video in a piece of software they know how to use (i.e. maya/poser/etc?), can encode  a bink2 video with relative triviality but making the video would be the hard part.  Of course, that says nothing about using video's you take of physical things, witness the number of "alien" things that are little more than dyed/painted terrestrial objects of mundane origin used in tv  or the varieties of animation used in robot chicken that make very little attempt to not look like something put together last night by an art student when compared to the high end production studio equivalents.... Maybe a visit to a junkyard/home depot, some purple spray paint, paper mache. tin foil, and a little creativity could make that yor event  example a spiffy video :) .


What I am testing, and eventually will ask permission for, if I managed to get a bink 2 sdk is the ability to convert the galciv 2 bik's to bk2's to use for modded event files, as a bit of fan service for some of the old campaign events. Like the Yor event above for instance who would thus become an animated Yor rather than just a static one.

For my first pack i'd like to do a 'lore' based pack and it would be a nice touch to reuse the old resources for events or minor races, this relies on a, me getting an evaluation sdk for not too much money invested (i've link this thread to bink in the email) b, galciv devs not minding the resources being used in a galciv mod and c, me being able to convert it successfully anyway.

Either way, it's a fun test for any kinds of bik files that are usable so it isn't time wasted, and I am enjoying finding out the boundaries in the files. I can possibly see myself able to animate some of my own stuff the convert it to bink in the future, but it's been awhile since I used Daz for example.