Guide to PathPrerequisites

Misc:

- TechnologyPrerequisites are actually PathPrerequisites preceeded by ".../ClassEmpire/ClassResearch" (S)

- You can check for multiple tags at once. (S)

[More to come]

New/extra planet prefabs & materials

[Rough]

This is not live yet; this is not organized. This is just collecting information that seems noteworthy.

From @MonAmiral in Discord: 

Hey folks, I've added new planet prefabs and materials which aren't used in the vanilla game

it means you will be able to add new planet types/unique planets with their own visuals, instead of having to modify a vanilla one

I don't think it'll be public before the end of the modding contest though

Names must be PlanetTypeCustom01~20 and UniquePlanetCustom01~10

20 types, and 10 uniques

I've created the data only for the first type, as an example

(so you'll have to override the first one and add the other ones)

Note that mods that add new planet types might not be compatible with each other, because they might either use the same planet types, or simply because they override the same GalaxyGeneratorWeightTable

(like, if it replaces the content of "StarTypeAcademy_PlanetTypes")

and...

The prefabs I have added can use the vanilla XmlMapping for ClassPlanet.Body (what CyRob linked)

So you just have to add the descriptor PlanetTypeCustom01 in SimulationDescriptors.xml

list it as a valid type in PlanetGameplayTypeDefinitions

and add it to a GalaxyGeneratorWeightTable such as StarTypeYellow_PlanetTypes

they'll naturally spawn, and use the new prefab, whose visual you can override with a PlanetRemappingDefinition

There are a lot of other things to do, like create the colonization constructible (required for colonization, even if not doing it via Construction queue), list it as a colonizable planet for minor factions, add GuiElements and set the FIDSI values

but it's mostly copy-paste

and a code example from @Cyrob from his Community Mod Project:

<XmlMapping Name="ClassPlanet.Body"><GameObject Name="Format('{0}.Body({1})', $(Type), $(GUID))" Prefab="Format('Prefabs/Game/Environment/Planet/PlanetBody_UniquePlanetTerrans_00')" Condition="$(Type) eq ('PlanetTypeGlobalCity')"/><Fallback><GameObject Name="Format('{0}.Body({1})', $(Type), $(GUID))" Prefab="Format('Prefabs/Game/Environment/Planet/PlanetBody_UniquePlanetSykagoja_00')" Condition="$(Type) eq ('PlanetTypeGlobalFarm')"/><Fallback><GameObject Name="Format('{0}.Body({1})', $(Type), $(GUID))" Prefab="Format('Prefabs/Game/Environment/Planet/PlanetBody_UniquePlanetTimeLords_00')" Condition="$(Type) eq ('PlanetTypeGlobalLab')"/><Fallback><GameObject Name="Format('{0}.Body({1})', $(Type), $(GUID))" Prefab="Format('Prefabs/Game/Environment/Planet/PlanetBody_UniquePlanetTor_00')" Condition="$(Type) eq ('PlanetTypeGlobalForge')"/><Fallback> <GameObject Name="Format('{0}.Body({1})', $(Type), $(GUID))" Prefab="Format('Prefabs/Game/Environment/Planet/PlanetBody_{0}_00_{1}', $(Type), $(ExplorationState))"/> <Fallback>  <GameObject Name="Format('PlanetGeneric.Body_{2}({1})', $(Type), $(GUID), $(ExplorationState))" Prefab="Format('Prefabs/Game/Environment/Planet/PlanetBody_Generic_00_{0}', $(ExplorationState))"/>  <Fallback>   <GameObject Name="Format('{0}.Body({1})', $(UniquePlanet), $(GUID))" Prefab="Format('Prefabs/Game/Environment/Planet/PlanetBody_{0}_00', $(UniquePlanet))"/>   <Fallback>    <GameObject Name="Format('{0}.Body({1})', $(Type), $(GUID))" Prefab="Format('Prefabs/Game/Environment/Planet/PlanetBody_{0}_00', $(Type))"/>    <Fallback>     <GameObject Name="Format('{0}.Body({1})', $(Type), $(GUID))" Prefab="Prefabs/Game/Environment/Planet/PlanetBody_PlanetTypeTerran_00"/>    </Fallback>   </Fallback>  </Fallback> </Fallback></Fallback></Fallback></Fallback></Fallback></XmlMapping>

And one more code example from @Cyrob in Discord:

<GameObject Name="Format('{0}.Body({1})', $(Type), $(GUID))" Prefab="Format('Prefabs/Game/Environment/Planet/PlanetBody_UniquePlanetTerrans_00')" Condition="$(Type) eq ('PlanetTypeGlobalCity')"/>

 

"This makes the planet type I've added (PlanetTypeGlobalCity) use the PlanetBody_UniquePlanetTerrans_00 prefab (Raia)"

Guide to PathPrerequisite

[More to come]

Checking for quest completion

In QuestDefinitions[], in your <QuestDefinition> just before you close <ObjectiveSet>, create a <Reward>

For example:

...

<Reward Droplist="MyDroplist" Picks="1"/>

</ObjectiveSet>

...

In Droplists[], create a <Droplist>

For example:

<Droplist Name="MyDroplist">

<Unlock Name="MyUnlockName" SimulationTag="MyQuestTag"/>

</Droplist>

You can then use a <PathPrerequisite> with the following pattern:

<PathPrerequisite Inverted="false" Flags="Prerequisite,Discard">../ClassEmpire/ClassQuests,MyQuestTag</PathPrerequisite>

... to check to see if your quest has been completed.

See also:

Guide to PathPrerequisite

Best Practices: Understanding Scope

Whether you're making your own game--or just creating a mod--scope is probably the most important thing to keep in mind.

This video from Extra Credit is my favorite explanation of scope:

As hobbyist game designers--or maybe just enthusiastic players--everything starts with, "This game would be so much cooler if..."

The moment we make a change, we start to get excited!

We're adjusting the world. 

We're changing things. 

Fixing them!

And in our heads, we're always making things better through our changes.

That's part of the magic of modding. You're not paying for your own time, and so you have the freedom to dream up pretty much anything. 

It feels like you have unlimited resources. 

It feels like you can accomplish anything.

But you don't have unlimited resources (aka time and passion) and if you don't get your scope down early, you're probably not going to accomplish much at all.

Personal Story:

My very first mod for an Amplitude game was a cocky, little thing called Tales of Auriga for Endless Legend.

My scope was easy to define: Everything!

I figured out how to do a lot of neat things, but I actually accomplished very little.

I classify that mod--it doesn't even work with the last release of EL--as a catastrophic failure!

And to be fair, I had a lot of fun designing it.

I got passionate about coding and organizing, and I can honestly say that it has inspired me and that I learned a lot from that experience.

I believe that, as long as you're prepared to throw all your work away at the end, go for it and have fun with a massively-scoped mod.

So what's the alternative?

I personally believe in smaller, focused, modular mods that combine together to create something amazing.

Helpful Links:

- Extra Credits: Game Design: 87 Videos on Game Design

- 5 Tips to Narrow Your Game’s Scope

Guide to HeroDefinition

<HeroDefinition> is found in:

Simulation/HeroDefinitions.xml

HeroDefinitions have a very strict format. You must include every part of the HeroDefinition.

An example of a complete <HeroDefinition>:

<HeroDefinition Name="YourHeroName">

<Skill Name="HeroSkill01Sophons01"/>
<Skill Name="HeroSkill02Sophons01"/>

<Affinity Name="HeroAffinitySophons"/>
<Class Name="HeroClassAdministrator"/>
<Politics Name="HeroPolitics01"/>

<ShipDesign Name="ShipDesignHeroSmall04Defender"/>

<SkillTree Name="HeroSkillTreeGeneric"/>
<SkillTree Name="HeroSkillTreeSophons"/>
<SkillTree Name="HeroSkillTreeAdministrator"/>

<LevelUpRuleReference Name="HeroLevelUpRule"/>

</HeroDefinition>

The Name property in <HeroDefinition>: 

<HeroDefinition Name="YourHeroName">

... must be a unique name.

If you use a name that already exists, you will overwrite the previous hero.

The <Skill> tag:

<Skill Name="HeroSkill01Sophons01"/>

...defines the starting skills for the hero

You can find the starting skills created by Amplitude in:

Public/Simulation/HeroSkillDefinitions[*].xml

The Name property you're looking for in the <Skill> tag of <HeroDefinition> is the same as the Name property in the <HeroSkillDefinition>

For example:

<HeroDefinition Name="YourHeroName">

<Skill Name="HeroSkill01Sophons01"/>

...

and...

<HeroSkillDefinition Name="HeroSkill01Sophons01">

<SkillLevel Name="HeroSkill01Sophons01_1">
<ShipSimulationDescriptorReference Name="HeroSkillShip25_FleetDefense_Percent_0"/>
<MasteryLevel Class="HeroMasteryCommand" Levels="1"/>
</SkillLevel>

</HeroSkillDefinition>

However, these <HeroSkillDefinition> actually lead to another file:

Public/Simulation/SimulationDescriptors[HeroSkill].xml

I have found that the easiest way to set starting skills--unless you plan to create your own--is to work backwards from SimulationDescriptors[HeroSkill].xml

At the end of the file--currently after line 1219--you will find a section labeled "Starting Skills"

You can read through those skills until you find a skill that fits your new hero. 

For example:

<SimulationDescriptor Name="HeroSkillSystem59_Dust_Flat_0" Type="HeroSkillSystem" IsSerializable="false">

<Modifier TargetProperty="SystemMoney"Operation="Addition"Value="15"Path="ClassColonizedStarSystem" />
<!-- FEEDBACK FOR SCAN VIEW -->
<Modifier TargetProperty="BonusHeroSystemDust"  Operation="Addition"Value="15"Path="ClassColonizedStarSystem" TooltipHidden="true"/>

</SimulationDescriptor>

... increases the Dust produced by a system by 15, which is perfect for my new economic advisor hero.

You can then take the Name property of the SimulationDescriptor that you want to use, for example:

<SimulationDescriptor Name="HeroSkillSystem59_Dust_Flat_0" Type="HeroSkillSystem" IsSerializable="false">

...and do a search in HeroSkillDefinitions.xml to find a <HeroSkillDefinition> that is already set up with that skill.

I found two skills already set up:

<HeroSkillDefinition Name="HeroSkill02Eyders01">

<Tags>ColonizedStarSystem</Tags>
<SkillLevel Name="HeroSkill02Eyders01_1">
<SystemSimulationDescriptorReference Name="HeroSkillSystem59_Dust_Flat_0"/>
<MasteryLevel Class="HeroMasteryWit" Levels="1"/>
</SkillLevel>

</HeroSkillDefinition>

and...

<HeroSkillDefinition Name="HeroSkill02Unfallen02">

<Tags>ColonizedStarSystem</Tags>
<SkillLevel Name="HeroSkill02Unfallen02_1">
<SystemSimulationDescriptorReference Name="HeroSkillSystem59_Dust_Flat_0"/>
<MasteryLevel Class="HeroMasteryWit" Levels="1"/>
</SkillLevel>

</HeroSkillDefinition>

If I want to take a shortcut, I can simply use either of these skills for my new hero.

For example:

<HeroDefinition Name="YourHeroName">

<Skill Name="HeroSkill02Eyders01"/>

...

or...

<HeroDefinition Name="YourHeroName">

<Skill Name="HeroSkill02Unfallen02"/>

...

Warning!

If Amplitude (or another mod) ever modifies these <HeroSkillDefinition> it will also modify your hero's skills.

For this reason, you may wish to create a completely new <HeroSkillDefinition> for your hero.

See also:

Creating new hero skills

For the Name property of <Affinity>:

<HeroDefinition Name="YourHeroName">

...
<Affinity Name="HeroAffinitySophons"/>

...

... you can pick any of the affinity names from:

Simulation/HeroAffinityDefinitions.xml

For the Name property of <Class>:

<HeroDefinition Name="YourHeroName">

...
<Class Name="HeroClassAdministrator"/>

...

... you can pick any of the hero class names from:

Simulation/HeroClassDefinitions.xml

For the Name property of <Politics>:

<HeroDefinition Name="YourHeroName">

...
<Politics Name="HeroPolitics01"/>

...

... you can pick any of the politics names from:

Simulation/HeroPoliticsDefinitions.xml

For quick reference:

01: Industrial

02: Scientist

03: Pacifist

04: Ecologist

05: Religious

06: Militarist

[More to come]:

<ShipDesign Name="ShipDesignHeroSmall04Defender"/>

<SkillTree Name="HeroSkillTreeGeneric"/>
<SkillTree Name="HeroSkillTreeSophons"/>
<SkillTree Name="HeroSkillTreeAdministrator"/>

<LevelUpRuleReference Name="HeroLevelUpRule"/>

Unlocking your new heroes from a quest

In QuestDefinitions[], in your <QuestDefinition> just before you close <ObjectiveSet>, create a <Reward>

For example:

...

<Reward Droplist="MyDroplist" Picks="1"/>

</ObjectiveSet>

...

In Droplists[], create a <Droplist>

For example:

<Droplist Name="MyDroplist">

<Hero Name="MyNewHero" Spawn="true" Level="10"/>

</Droplist>

Important!

There are two optional properties in the droplist example above.

First, in the following example:

<Hero Name="MyNewHero" Spawn="true" Level="10"/>

... Spawn="true" tells the game that it should immediately give the empire a copy of that hero.

Second, in the next example:

<Hero Name="MyNewHero" Spawn="true" Level="10"/>

... Level="10" tells the game to make that hero level 10 when it is spawned.

See also:

- Creating a new hero

Unlocking your new heroes: Overview

You can unlock your buildings through a variety of methods, including:

- Unlocking your new heroes from a quest

[More to come]

Creating a new hero

To understand the various ways in which you can unlock your new hero, please see:
- Unlocking your new heroes: Overview

In Simulation/HeroDefinitions.xml, create a new <HeroDefinition>

For example:

<HeroDefinition Name="YourHeroName">
<Skill Name="HeroSkill01Sophons01"/>
<Skill Name="HeroSkill02Sophons01"/>

<Affinity Name="HeroAffinitySophons"/>
<Class Name="HeroClassAdministrator"/>
<Politics Name="HeroPolitics01"/>

<ShipDesign Name="ShipDesignHeroSmall04Defender"/>

<SkillTree Name="HeroSkillTreeGeneric"/>
<SkillTree Name="HeroSkillTreeSophons"/>
<SkillTree Name="HeroSkillTreeAdministrator"/>

<LevelUpRuleReference Name="HeroLevelUpRule"/>
</HeroDefinition>

Notes:

- HeroDefinitions have a very strict format; you must include every part of the HeroDefinition

See also:
- Guide to HeroDefinition

In GUI/GuiElements[*], create a new <HeroGuiElement>

For example:

<HeroGuiElement Name="YourHeroName">

<Title>%YourHeroNameTitle</Title>
<Description>%YourHeroNameDescription</Description>
<Icons>
<Icon Size="Medium" Path="Gui/YourHeroName_Medium"/>
<Icon Size="Large" Path="Gui/YourHeroName_Large"/>
<Icon Size="Mood" Path="Gui/YourHeroName_Mood"/>
</Icons>

</HeroGuiElement>

Important!

The <Title> is especially finicky, and it will not find the localization key unless you adhere to the following naming format:

<Title>%YourHeroNameTitle</Title>

Your localization key MUST end with "Title" and it cannot have an underscore preceding it.

For example, the following would not work for me:

<Title>%YourHeroName_Title</Title>

See also:

- Guide to GUIElement

In Localization/english/ES2_Localization_Assets_Locales.xml, create two <LocalizationPair>

For example:

<LocalizationPair Name="%YourHeroNameTitle">Name Of Hero</LocalizationPair>
<LocalizationPair Name="%YourHeroNameDescription">Flavor text for new hero</LocalizationPair>

Notes:

- The LocalizationPair Name attributes should match up with what you put into the <Title> and <Description> tags in the GuiElement (see above)

- This is what adds your title and flavor text to the GUI

See also:

- Guide to Localization

How to make shields absorb all damage

Objective:

- You want shields to absorb all damage from all weapons until they are depleted.

In SimulationDescriptors[ModuleWeapon].xml, found in:

Simulations/Battles/

... you'd need to adjust the property for each of the base weapons.

For example, in:

<SimulationDescriptor Name="ClassModuleWeaponKinetic"  Type="ClassModuleWeapon">

... you will find a <Modifier> with a TargetProperty="ShieldPenetrationFactor"

For example:

<Modifier TargetProperty="ShieldPenetrationFactor" Operation="Addition" Value="0.9" Path="ClassModuleWeapon" TooltipHidden="true"/>

You simply need to change:

Value="0.9"

to...

Value="0"

Tips:

- There are probably many other ways to do this.

You cannot alter the game's soundtrack (or it is very difficult to do)

The music is compiled when the project is built. (S1) (S2)

Tips:

- There may be a very complicated workaround. (S)

See also:

- ES2 modding limitations: the Unity Engine & prefabs

You cannot alter starting anomalies or the size of home planets

Both of these things are controlled from outside of the xml and cannot be currently modded. (S)

Tips:

- There may be a workaround for anomalies, if you add them via a quest, but this is more advanced/complicated. (S)

Publishing to the Steam Workshop

[More to come]

Where are mod files stored?

Tips:

- Make sure you are absolutely sure where your active installation for ES2 is located; you can have older, abandoned installations if you have multiple Steam Libraries (S)

Mods can be created, installed and/or loaded from default two locations.

The first--aka Local--is located at:

Documents/Endless Space 2/Community/ModFolder/ModContents

The second location--aka Workshop--is located at 

SteamLibrary/steamapps/workshop/content/392110/ModID/ModContents

392110 is the number assigned to ES2 on Steam.

You can see this in the web address of the store page on Steam:

http://store.steampowered.com/app/392110/Endless_Space_2/

The ModID is a number assigned to your particular mod.

You can find this number in two places.

First, it can be located in PublishedFile.Id in your mod's root folder. This file is created the first time you publish your mod to the Steam Workshop and should never be edited/deleted.

Second, you can find this in the web address of a mod subscription page:

http://steamcommunity.com/sharedfiles/filedetails/?id=1077924717

In this case, 1077924717 is the number assigned to the G2G Balance Mod published by Amplitude for testing purposes.

Notes:

- You can use this information find your mod once you publish it to the Steam Workshop

- You can also use this information to download and study other mods for reference

See also:

- Publishing to the Steam Workshop

- Studying other mods

Preface

This whole forum is a wonderful resource for modding ES2. This thread is my personal contribution and I hope you find it helpful. I will curate this thread with descriptions, links, discussions and guides that I find helpful and informative.

Also, please note there may be errors in this guide. I'm a hobbyist modder and a volunteer; and I'm learning with everyone else. If you do find an error, or want to contribute something helpful, please feel free to send me a PM, or to post here with your correction.

(S) provides a link to source material which credits the author and provides context/examples

* Items marked with an asterisk are incomplete/placeholders for future content; needed to give this guide structure.

FAQ

-

Current Modding Limitations

- ES2 modding limitations: the Unity Engine & prefabs

- You cannot add new animations for heroes and/or factions

- You cannot add new models

- You cannot alter starting anomalies or the size of home planets

- Some faction traits are hard-coded *

- You cannot alter the game's soundtrack (or it is very difficult to do)

Best Practices

- Understanding Scope

- The best way to add new content in your mod

- Think twice before making a "simple" change to a base game definition

- Try not to replace base game files & definitions (unless that is your intention)

- Studying other mods *

General Information

- Where are mod files stored?

- Publishing to the Steam Workshop *

- How the game loads your mod files *

- Guide to DataTypes *

- Guide to Localization *

- Guide to GUIElement *

- Guide to SimulationDescriptor *

- Guide to PathPrerequisitive *

Buildings (aka Star System Improvements)

- Unlocking your custom buildings: Overview *

- Unlocking your custom buildings from a quest

- Creating a custom building

- Guide to StarSystemImprovementDefinition *

Combat

- How to make shields absorb all damage

Heroes

- Unlocking your new heroes: Overview

- Unlocking your new heroes from a quest

- Creating a new hero

- Guide to HeroDefinition

- Creating new hero skills *

Quests

- Checking for quest completion

- Unlocking your custom buildings from a quest

- Unlocking your new heroes from a quest

Misc/Unsorted

- New/extra planet prefabs/materials

Other Helpful Info/Links (Alphabetical)

- Example Hero Example Mod (by Amplitude)

- Faction Traits and Example Mod (by Cyrob)

- Manual for Modding Endless Space 2 (by Dagart)

Guide to DataTypes

[More to come]

Some faction traits are hard-coded

[More to come]

You cannot add new models

- This is not currently possible in ES2

- The game was developed in the Unity engine, and this is a limitation of the game engine

See also:

- ES2 modding limitations: the Unity Engine & prefabs