It is now possible to mod Endless Space! For now, only XML-based modifications are possible, but we'll continue working on tools to allow you to mod the game even further (UI, models, etc...). And very soon, you'll be able to add in your own icons, portraits, etc...



This thread will serve as a guideline for specific modding blocks. I will frequently add new tutorials depending on what type of help modders need. Feel free to contact me if you've written a tutorial (and it is easy enough to follow), I'll add it to this thread.



Anyways, enjoy.



The Modding Tutorial is available as a PDF too. The version will be regularly updated with recent changes. The current version is v. 2.0

Modding Tutorial.pdf





The List of customizable icons/portraits with their size and XML occurrences

icons.pdf



The demo mod archive to create your own planets and ships

CustomPlanetsAndShips.rar



If you have trouble downloading a file do this and try again.



1. Log out of the forum and log back in.

2. Else try a different browser (firefox vs IE, etc)

3. Else clear your browser cookies.



(moderator action: davea: split all non-dev team posts into separate thread; locked thread. This will keep this thread clean. Of course the dev team can unlock/relock to add more posts.)

HOW TO CREATE A MOD



[LIST=1]



PC

Go to “Your drive”\Steam\SteamApps\common\Endless Space and copy the Public folder except: Audio, Movies, Registry.xml

Go to My Documents\Endless Space (this is also where your saves are stored).



For Mac (For "how to access the User Library with Mac OS X 10.7+ , go here:

Go to "~\Library\Application Support\Steam\SteamApps\common\Endless Space"

"Right-click" the Endless Space package and click "Show package contents"

Copy the Public folder except: Audio, Movies, Registry.xml

Go to "User Library\Application Support\Endless Space".

Create a new folder and name it “Modding”.

Paste the lighter Public folder inside that new folder.

Rename it to whatever you want to call your mod.

Create a Zip file and upload it on the internet.

[/LIST]



HOW TO INSTALL A MOD



Assuming you downloaded a zip file containing the desired mod.



[LIST=1]

If not already existing, create a new folder called Modding in My Documents\Endless Space

Unzip the file’s content to My Documents\Endless Space\Modding



For Mac:

Use "~\Library\Application Support\Endless Space\Modding" instead

[/LIST]



HOW TO RUN A MOD



First, install the mod (refer to “How to install a mod”). Then:



[LIST=1]

Go to Mods on the title screen.

Select your mod.

Load it!

[/LIST]





HOW TO KEEP A MOD LOADED

In Steam, in the launch options dialog box, put "+mod YourModDirectoryName".





HOW TO ADD CUSTOM TECH ICONS

/#/endless-space/forum/37-modding/thread/16353-tutorials-for-modding-es





HOW TO ADD HERO PORTRAITS

/#/endless-space/forum/37-modding/thread/16353-tutorials-for-modding-es

The Tech tree is separated in 4 branches, each independent. There is therefore an XML file for each branch: TechnologyExpansion.xml, TechnologyWarfare.xml, TechnologyDiplomacy.xml and TechnologySciences.xml.



HOW TO ADD A TECHNOLOGY IMPROVEMENT



Setting up the Tech's icon in the tree



[LIST=1]

Open MyMod\Simulation \TechnologyExpansion.xml and copy/paste a block.

The techs are sorted by “circle”. The ones at the beginning concern the innermost circles whereas the ones at the end are the most distant from the center.

Set the cost to what you want (industry), isUnique=true.

X and Y represent polar coordinates. Imagine that the whole tree is based on a cross (North, East, South, West = Warfare, Science, Expansion, Diplomacy). There is one “cross segment” per branch. Each (x,y) is based on their respective segment.

• X is the polar angle (clockwise) from that segment to the tech’s icon in the tree. For example in the Expansion tree, a positive value for X will place the tech on the left side. A negative value will place it on the right.
• Y is the arc’s length, from the origin to the tech’s icon.
  
  

Category = The tree’s category (here: ExplorationExpansion).

PathsPrerequisites represent faction affinities or traits required to access the tech. The syntax uses classic logic (or,and,!). Ex: $(TraitX) and !$(TraitY)

TechnologiesPrerequisites is unused (at present).

TechnologiesDependencies is the field that will create the visual links in the tree. Only list the techs that are “immediate parents” of your tech (or else, witness a super web of interconnected techs).

Unlockable lists the improvements/changes/modifications that your tech unlocks. Use your unlock’s name (ID) and a Standard access. That ID references the unlock’s description (in another XML file). So make sure you use the same name here as where you describe the unlock! For now, simply copy/paste an existing unlockable, we will create ours in a minute.

GUI has a title and a description. For a localized version of your text, refer to “How to localize your texts”. The icon (as of 23/07/2012) must be an existing one. Copy/Paste the path desired.

[/LIST]



Creating the unlockable improvement



[LIST=1]

For the purpose of this tutorial, we will create an empire improvement but it works for any type of improvement. Therefore, open EmpireImprovement.xml.

Copy/Paste an block.

Descriptors is the unlockable tech’s ID that is used across the XML files. Make sure you use the same name everywhere. Let’s create “ForceField1”.

GUI contains the unlock’s description and title. As usual, refer to “How to localize your texts” for modding in several languages. The tech’s actual effect(s) will be automatically displayed in III).

[/LIST]





Applying the actual improvement/changes/modifications that your tech unlocks



[LIST=1]

Before creating the improvement, make sure that your icon is correctly created in the tech tree. Launch your mod and go check.

Your icon shows up at the right place, with the right unlock(s) great! Now time to create the unlock’s effects. Continuing on our Force Field improvement, open EmpireDescriptor.xml . The descriptors contain the game elements’ behavior & stats. That is where you will access and modify most variables. All of them are defined in a SimulationObjectDescriptor (for a Hero, an Empire, a StarSystem…) containing various SimulationObjectPropertyDescriptor. Most of them are at the beginning of the corresponding descriptor files.

Add a SimulationObjectPropertyModifierDescriptors (plural) block. It will contain SimulationObjectPropertyModifierDescriptor (singular) blocks that modify the object’s values.

Here is how it works:

• TargetProperty: The variable you want to modify. The target properties accessible can be found at the beginning of the corresponding XML descriptor files (ex: You want to access the FIDS for your Empire, the property will be in EmpireDescriptor.xml).
• Value: By how much you want to modify the variable (positive or negative)
• OperationType: Percent, Addition or Multiplication.
• By using SimulationObjectPropertyBinaryModifierDescriptor (notice “binary” in the name), you can use two operations at once. Eg:
  
  
  • TargetProperty = “Approval” OperationType=”Addition” BinaryOperationType=”Multiplication” Left=”8” Right=”4” => Approval+ (4*8). The BinaryOperation is computed with Left and Right, then that result is computed with the (normal) Operation on the TargetProperty.
    
    
  
  
  
• Path: Very important. It shows what TargetProperty you want to modify exactly.
  
  
  • Ex: You want to modify Approval for all Empires, affecting all their systems then Path=”ClassEmpire/ClassStarSystem”.
  • However, if you want to modify Approval only for a specific affinity, add that affinity using a “,”. Path = “ClassEmpire,AffinityAmoeba/ClassStarSystem”.
    
    
  
  
  
  
  

Drop to your knees, your eyes watery and a sly smile on your face, as your über tech is now free roaming the endless, unforgiving and merciless space.

[/LIST]

HOW TO ADD A FACTION TRAIT



Setting up the trait



[LIST=1]

Open MyMod\Simulation \FactionTrait.xml.

Copy the empty trait template at the beginning of the file. In the XML file:

• Name: the trait's "id", serves as a tag to identify it in any xml file. Different levels for a same trait should have different names (ex:Crusaders1, Crusaders2,etc).
• Root: If your trait has several levels of improvement, this is the “base” name (ex: Crusaders).
• Family : The trait’s category in the GUI’s left column, where the trait will be stored (ex : TraitPopulation).
• Descriptors: Use the trait’s Name.
• Prerequisites: Lists all the traits that must or must not be selected for this trait to be used (ex: !AntiCrusaders1,!AntiCrusaders2, PreCrusaders, BabyCrusaders).
• Title: If you want your faction trait to be localized, use”%” to reference a localization key (ex: %CrusaderTitle) and go to 1). Otherwise skip to 2).
  
  

[LIST=1]

Localized text version: Open Localization_Locales.xml in MyMod\Localization\english (or French /German). Create a new LocalizationPair with the %name (ex: %CrusaderTitle) and the actual name (ex: Crusader Crazy). Translate appropriately in the other Localization_Locales files.

Simply write the trait’s name

[/LIST]

• Description: Same as title.
• Your trait is now set up.
  
  

[/LIST]



Creating the actual trait



[LIST=1]

Open MyMod\Simulation\EmpireTraitDescriptor.xml

Copy an entire SimulationObjectDescriptor sample, at the beginning of the file. In the XML file:

• Name: Refers to the same name as in the FactionTrait.xml file.
• Type: The “base” name for this trait (ex: Crusaders)
• Serializable: True.
• Inside SimulationObjectPropertyModifierDescriptors (plural) is where you will add your trait’s modifications. You can add as many SimulationObjectPropertyModifierDescriptor (singular) as you want. Here is how it works:
  
  
  • TargetProperty: The variable you want to modify. The target properties accessible can be found at the beginning of the corresponding XML descriptor files (ex: You want to access the FIDS for your Empire, the property will be in EmpireDescriptor.xml).
  • Value: By how much you want to modify the variable (positive or negative)
  • OperationType: Percent, Addition or Multiplication.
  • By using SimulationObjectPropertyBinaryModifierDescriptor (notice “binary” in the name), you can use two operations at once. Eg:
  • • TargetProperty = “Approval” OperationType=”Addition” BinaryOperationType=”Multiplication” Left=”8” Right=”4” => Approval+ (4*8). The BinaryOperation is computed with Left and Right, then that result is computed with the (normal) Operation on the TargetProperty.
  • Path: Very important. It shows what TargetProperty you want to modify exactly.
  • • Ex: You want to modify Approval for all Empires, affecting all their systems then Path=”ClassEmpire/ClassStarSystem”.
    • However, if you want to modify Approval only for a specific affinity, add that affinity using a “,”. Path = “ClassEmpire,AffinityAmoeba/ClassStarSystem”.
    • Other ex: You want to change the DamageMax for Lasers only. This is the Path you would use: ClassEmpire/ClassFleet/WeaponModule, Laser. It is equivalent to ClassEmpire/ClassFleet/Laser.
      
      
    
    
    
    
    
  
  
  
  
  

Launch the game, go to Custom Faction creation, click on the category that was filed under “Family” in FactionTrait.xml

Witness a glorious display of Endless beauty and wonder. Your trait, all fresh and ready to rumblespace.

[/LIST]

How to create a planet anomaly



There are two important files for creating planet anomalies: Anomaly.xml and PlanetDescriptor.xml.



Visual Aspect

[LIST=1]

Open Anomaly.xml. Your anomaly’s visual aspect is defined here.

Copy/Paste an AnomalyEffect block. Name it with an ID that you will use in PlanetDescriptor.xml.

PlanetRimPower represents how powerful the visual effect is. The lower the value, the stronger the effect.

PlanetRimColor and AtmosphereColor are R,G,B, alpha (transparency) values for the effect, from 0 to 255.

Use an existing prefab if your anomaly requires one. Place it either in AnomalyPrefabPlanet or AnomalyPrefabDummy.

[/LIST]





Effects

[LIST=1]

Open PlanetDescriptor.xml

Search the comment “Anomaly list”.

Copy a SimulationObjectDescriptor block, name it with the same ID as in Anomaly.xml. Use the type PlanetAnomaly.

To apply effects, refer to point 4) of “How add a faction trait”.

Anomalize that endless space!

[/LIST]





Adding the anomaly

[LIST=1]

Open GalaxySettings.xml

Search “Anomalies”

Add a PlanetAnomalyPerPlanetType tag with your newly created anomaly for each PlanetType.

Add a weight. NB: The keyword used is “probability” but it really is a weight. If AnomalyA has “Probability=1” and AnomalyB has “Probability=2”, then B has twice more chances of appearing.

[/LIST]



Adding a description

[LIST=1]

Simply open Localization_Locales.xml in MyMod\Localization\english (or French , German)

Search “PlanetAnomaly”.

Copy a “title” line and a “description” line, then change the number accordingly.

Add your title and description between the tags.

[/LIST]

The method for creating mods given in the OP is not actually the best way to make mods. This involves copying 50+ files which you aren't changing. If you only want to change 1-2 files, you should change "standalone=true" in index.xml to "standalone=false" and then only copy the files you are changing. This works for files in AI and simulation, but not plugins; for plugins such as galaxy generator, you have to copy the whole directory even if you are just changing one file.



You should really edit index.xml after you copy it, to give your mod information.



Protip: if you make a syntax error in the xml, the game will hang at the loading screen. Regardless of whether or not you get a hang, you should really look at file /EndlessSpace_data/output_log.txt and search for the string "Modding". If there is a syntax error or other problem loading, the filename which causes the problem is listed in this file. Since the full pathname of the file is given, searching for "Modding" will find it. Note, even if the game does not hang and appears to run, you may still have a syntax error. I have created at least one example where this happens.

HOW TO ADD CUSTOM TECH ICONS



[LIST=1]

In Yourmod/Gui, create a folder with the name that you want, eg: TechIcons.

Place all your tech images there.[LIST=1]

They must be PNG files (for transparency).

64x64 in size.

[/LIST]

The name you give a specific icon is the one you used in the Gui block when creating the corresponding technology. By specifying TechIcons/MyIcon in the Gui block, the game will use your custom icon.



This is an example of a tech in TechnologyExpansion.xml:

[CODE]





%TechE27SowerDescription

[/CODE]



To add your custom icon MyIcon.png, located in YourMod/TechIcons/, change the bold line to :







[/LIST]



HOW TO ADD HERO PORTRAITS

[LIST=1]

Follow the same method as the one above. For convenience, add your pictures in a HeroPortraits folder for example.

The only difference concerns the portraits’ sizes. [LIST=1]

Large: 128x64

Small: 64x32

Wide: 284x128

[/LIST]

The pictures’ references go in Hero.xml. Supported extensions are jpg and png.

[/LIST]



HOW TO ADD CUSTOM HERO CLASS ICONS

[LIST=1]

Follow the same method as the one above. For convenience, add your pictures in a HeroClass folder for example.

The only difference concerns the portraits’ sizes. [LIST=1]

Large: 32x32

Small: 16x16

[/LIST]

[/LIST]



All sizes and locations in the XML files can be found in the OP

HOW TO ADD A PLANET



It is strongly advised to download the CustomPlanetsAndShips mod. The archive contains all (and only) the files necessary to create a mod with planets and ships.



CustomPlanetsAndShips.rar



Let’s add PlanetPinky, a joyful pink planet. It is advised to rename your modded files with a custom name “eg: PlanetColonization => CustomPlanetColonization”. You will then have to reference them in Index.xml, in order for the game to locate them.





Creating the planet’s properties & statistics



[LIST=1]

Copy the entire Plugins folder to your mod’s folder and modify GalaxySettings.xml by adding PlanetPinky whenever other planets are described. In this file, you will define the probability of luxury resources on your pink planet, the probability of appearance, of anomalies, temples, etc…It is also where you define home systems and starting planets for the factions, should you want to force a faction to start on your pink planet.

Note that even though you only modified GalaxySettings.xml, you still have to include the whole Plugins folder in your mod.

The Simulation folder contains the planet’s properties (in FIDS for example). You only need the following files:

• PlanetColonization.xml
• PlanetDescriptor.xml
• PlanetSizeModifier.xml (will override the planet sizes, explained below)
• TechnologyExpansion.xml (assuming you want to unlock your planet in that tree)
• Gui.xml

PlanetDescriptor.xml contains the planet’s properties. You define the FIDS there.

PlanetColonization.xml is the technology to colonize your pink planet. Add the wanted PathPrerequisites and AIPrerequisites. The icons in the Gui tag are the ones that will appear in the tech tree for ColonizePinky. Use classic sizes for that.

PlanetSizeModifier.xml is a custom file overriding the population on planets depending on their size. It isn’t possible to simply “add” the population value line for just PlanetPinky, all populations have to be referenced. For clarity purposes, it is wiser to therefore add a PlanetSizeModifier file containing the pop per planet size.

TechnologyExpansion.xml is used to display the tech containing your ColonizePinky.

Gui.xml is the image displayed in Planet View, you have to add one or the mod won’t load.

The Localization folder contains your xml localization files. You don’t need to copy all the existing lines, anything that is present in your custom file will override existing localization keys and use the news ones correctly.

To teach the AI how to colonize your Planet Pinky, you will have to add AI Parameters. Use existing files as a base (it’s a system of weights for FIDS). You don’t need to reference your CustomAIParameters.xml file in Index.xml BUT you strictly have to follow the path YourMod/AI/Parameters/yourfileshere.

[/LIST]





Importing your textures



Again, it is strongly advised to download the CustomPlanetsAndShips mod, as it contains “base” files for the textures, with the correct nomenclature and sizes.



In Index.xml, add a Templates tag, you will place custom models here.



[CODE]













[/CODE]



Reference is the name/path it'll be known as in game. This should not collide with any known prefab, except if you want to "overwrite" the source (aka change the ships of a faction for example)



Prefab is the source you want to base your mod on. Available prefabs:

• PL_Terran_A

• PL_Arid_A

• PL_Arid_B

• PL_Arctic_A

• PL_Barren_A

• PL_Barren_B

• PL_Desert_A

• PL_Desert_B

• PL_GasHelium_A

• PL_GasHydrogen_A

• PL_GasMethane_A

• PL_Jungle_A

• PL_Lava_A

• PL_Ocean_A



Folder is your modded texture folder. It contains all your textures in JPG. We use a system of cube map, where square textures are applied on a spheric model (the planet). It is necessary to respect the case for the nomenclature. Eg: PL_Pinky_A_Bk_DIFF.jpg (also try to use files that aren’t too large)



• PL_Pinky_A is the name you used for the Reference in the Planet tag.

• Bk = Back

• Bt = bottom

• Fr = front

• L = Left

• R = right

• Tp = Top

• DIFF = diffuse

• SPEC = specular



HaloColor is the general color you want to put on the planet halo. Values go from 0.0 to 1.0 (RGBA values)

HOW TO ADD A NEW SHIP MODEL



It is strongly advised to download the CustomPlanetsAndShips mod. The archive contains all (and only) the files necessary to create a mod with planets and ships.



CustomPlanetsAndShips.rar



Let’s add ship Anna_V_01. Models are OBJ files. In Index.xml, add a Templates tag, you will place custom models here (if you already created one to add a planet, simply continue the tutorial within that Templates tag).



[CODE]





[/CODE]



Reference is the name/path it'll be known as in game. This should not collide with any known prefab, except if you want to "overwrite" the source (aka change the ships of a faction for example).



Size : Small / Medium / Large



Prefab is the source you want to base your mod on. It is used to compute collisions, demis, etc. As of version 2.0, that prefab is fixed. The reason for this is that the Terran Medium has the most generic launch sites (dummies) for projectiles. In later versions, you will be able to define specifically what type of prefab you want.



Model is your modded model. Use OBJ for the model and MTL for your material. Base yourself on the “demo” ship contained in CustomPlanetsAndShips (Anna_V_01) for sizes and scale, and make sure your ship has the same orientation as Anna’s.

• Small = Anna’s size
• Medium = 2x Small
• Large = 2x Medium
  
  

Update: Modeling Guidelines by Ravine available here:

Modeling Guidelines for modding.pdf