This a starting guide for all that want to do their own events. Some pointers before I start.

Wishlist:

• A SimulationEvent which describes a change of diplomatic status between two empires. There is something like this for BattleStart, BattleTerminated, CityBesieged, etc. but not for that. The only one is if a surrender is signed, which does not help since it is difficult to get the winner and loser side.

Table of contents:

1. Which elements are needed for events?
2. Overview EventCategory
3. Overview Event
4. FAQ
5. Examples and their uses

1) Which elements are needed for events?

When you create a new collection, these two are what govern the events:

Please note, the first one is optional. You can safely use those, that already in the game. I tend to do new ones. The second is the collection for each event.

Aside from that, the rest are optional like effect descriptor you want to apply but are not necessary themselves.

2) Overview EventCategory

Events need to be assigned to an EventCategory. All settings here govern how the assigned events function.

Global: The event will fire global once

Narrative Event Definition Distribution: Since an event needs to be assigned to an EventCategory, this defines how the events are sorted and potentially fired.

Need Manual Trigger: Events In this category need a manual trigger from another event (will be shown later).

Consume Event upon trigger: The event will only fire once if this is ticked. Please note, you can override this setting on per event basis (will be shown later)

The rest are self explanatory or have a tooltip.

3) Overview Event

In this definition the event itself is build. There is a lot of ground to cover.

Definition

Category: Choose the category which governs how event are generally triggered.

Era Definition: Is mandatory. The event will only fire in the listed eras. Has no effect on events which are triggered by another event.

Trigger

Consume Event upon Trigger: Same setting as category, just for this particular event.

Prevent Event Removal: Event can fire several times.                 

Is Narrative Consequence: This means, this event is only fire by another event.

Simulation Event (not shown if above setting is ticked): Here you can select how the event is triggered. There are many events where you can check to fire this event or not.

Prerequisites: Here you can set up WHO will get this event. Leaving this blank, will show you events from other empires too. There are many possibilities, but most you will use the Empire_Self.

Variables 

Here you can check and set up variable collections which can be used in the event effects further down. This is also automatically a prerequisite check for the event to fire. You setup a name and what will be collected (All, First, Last, Any). 

In the above screenshot it wants to have an empire with the Babylon legacy trait. If there is no empire with that trait in the game and the variable will be empty, the event will NOT fire.

Most useful here: MajorEmpire, Empire_xx (like Empire_Settlements).

Has Count Condition: You can tick this to setup a count check. For the variable (and the event) to be valid, there needs to be n many entries with different operators like Equal, Greater or Less Than.

You can setup an event which will fire for instance only if less than 3 empires are in the game, or more than 8, etc. Or a specific number. Of course, you can also check for other things depending on you chosen element: number of pops, Holy Sites, number of units. I think almost anything than can be quantified can be used.

Element Prerequisites: Here you can finetune what will be stored in this variable. In the screenshot above, it checks for the Babylon legacy trait. The found empire (if any) will be stored under the variable name. Please note it is also important the Collection Selector and the Sort Property name.

Empire ID: Some variables or prerequisites want you to limit it to a specific empire id. The standard is Empire (MajorEmpire) which is the one who gets this event usually (meaning the empire controller). In the variables you can also check variables. For instance you can make a variable collection of the empire of Assyria (with the trait) and then make a second variable and get all their cities (you use the the variable name as Empire ID)

UI

Setup of the used picture, title and description of the event.

GeoLocation ID 

Here you can focus the view on an element from the setup variables. Make it a single variable.

Choices

Now the choices. These are the boxes you see to make a selection. Please note, the choices are normally separate (pages) instead of under each other. You can change the view slightly to the left where you add a new element.

Title and Description is what is shown on a button.

Instant: can be ticked to make the effects instant. Please note, you can give for example an empire 500 fame and apply a descriptor to something. The 500 fame will be given once. The descriptor stays until the end.

Duration: Only available if the Instant box is not ticked. Number in turns. Please note, it does take game speed into account and will multiply your number.

Prerequisites: not sure if and how they work in this place… so can’t say much about them

Narrative Event Effects

Here you add the different event effect this choice does.

Reversible: If this is ticked and you have a duration for the choice the effect will last until the duration is over and is then removed. This applies to EVERYTHING (from example above: each turn +500 fame and the descriptor effects apply and both get removed when its over). 

Simulation Event Effects: Most are self explanatory. You have stuff like AddFame, AddMoney, AddGrowth, Unlock stuff, trigger another event, apply status or descriptors, end the game etc.

Hidden: The actual effects are hidden in the choice box. Only title and description is shown, but effects are still applied as normal. (The omnipotent choice of the persona mod is like this)

AI Gain Values: Here you can setup values for the ai for some properties like food, military, etc. It is tied to the AI Archtype at the end. If no archtype is chosen, the values here are useless.

Target ID: The target where the effect is applied to, can also feature variable names. Please note that for status and descriptors, the target and the starting point of descriptors must be the same. If the target id is a MajorEmpire, so does the descriptor need to start from as MajorEmpire (watch the parenthesis).

Here you can select archtypes of personas and give them a weight. Or different weights for different personalities. How the weight is multiplied with the AI Gain values, I do not know.

Please note: If the archtype of the persona is NOT covered at all. That empire will ALWAYS choose the very first option of an event. So make the first one your fallback choice.

4) FAQ

Q: So can I make culture exclusive event chains?

A: Yes you can, use the descriptor validation and set it to the legacy trait. This can be even more elaborate with validating two specific empires and then make event chains around both of them and their interaction.

Q: Can I add events specific to transcendence empires?

A: Yes you can. You can even limit this to specific cultures. I made one which only fires if you take Babylon in era 1 and then transcend them. Gives you two choices. (Not publicly available) 

Please note, the legacy trait for era 2 is the legacytrait_era1_upgrade.

Q: Can I unlock new constructables (districts, units, infrastructures)?

A: Yes you can. But you need to add those to an invisible tech. Otherwise they will become available as soon as the building prerequisites are met. 

Q: I made an event which applies a descriptor to settlement stuff. It now shows "Unknown" as source.

A: Apply the descriptor with a status instead (use ApplyStatus in the event). This will show the used status category as source for this descriptor. You need to add the StatusCategory to the UI Mapper for your own text.

I will add more questions and answer from users when they come up.

5) Examples

Animal Kill Event: Discord link

An event which gives a one time bonus (40 food to the army and 150 incluence) after winning against an animal once per animal type. Shared on discord and made by me. This a unity database, which you can import into your own project: 

Player Persona Handicap: Player Persona Handicap Bonus mod for Humankind - mod.io

Event chain on mod.io (also from me). You get some permanent bonuses in different categories.

Trigger another event:

I will use my persona handicap mod for this. The following screenshot show the very first window where you make the choice which categories you want to choose from.

I added the Event Effect "TriggerNarrativeEvent". For each additional window I added a new TriggerNarrativeEvent effect. Only the first one is not collapsed in the screenshot, but the setting is the same. Each possible consequence needs a weight. YOu can have several consequences in one event. I split it here so each window gets fired.

The stack should be which variables are ported to the triggered event.

Apply a descriptor to a territory after a district has been built (this allows infrastructure to have per territory effect if a specific district is build in that territory)

I saw that someone on discord asked for this, if this was possible. And yes it seems to be.

Goal: Make the City Watch only apply their Stability once per Territory IF in that territory is a garrison. You can built the garrison any number of times in that territory, but any beyond the first does not grant any benefit from the infrstructure.

Mandatory: Have a descriptor you want to apply. Do not forget the validationmapper and effectmapper for that. 

First we change the infrastructure.

Next we setup the event:

The event goes as follows: when a district is built, check if its the correct district type. Then count the territories which have a garrison, but not the tag.

As for the effect itself. Apply the tag to the territories with the above limitations.

Changed city watch:

Result (City with three territories. In one are 5 garrison, in a second 1. Third has none):

I added two more things to the FAQ and also an example which describes a territory based effect which relies on a specific type of district but is independent on their numbers (one is enough, but many will not add more benefit of the territory effect) since I posted this originally. Depending on *when* you visited this thread you may have missed them.

Anyway, here is a new example.

Using an event to unlock stuff with 2 tech requirements.

In this example we use the blue highlighted one. 

Aside from the usual stuff which describes your unlocked Unit/Building/District/Tech etc. you need one thing. An event and maybe a category.

Also to make the desired unit not available asap, you need to lock it behind a technology (HiddenTech element). If you make a new technology, it has some mandatory fields, otherwise you cannot start a game (it will show you an error). But I will not go into details with that. You can still look into it in the download link for the package.

Foreword: There is some limitation to this. IF you make your new super powerful unit visible on the techscreen, it is still possible to research the tech manually. You can make the tech hidden to circumvent this (or make it super expansive to research), but you as the player may not know about this then.

You can do another event which will describe this or make this knowledgeable in another way. I do not know if it is possible to make some fake units in the tech screen just for having some info on the unit and how to unlock them since I have not really dabbled with the techscreen or making new unlockables at all. Maybe someone else can shed light on this.

Anyway, the core of this is the event:

As you can see, I added 3 requirements:

- your empire needs to trigger this event

- added two techs as prerequisite for the event to trigger (Calendar and Domestication, and you need both researched). The triggers can be something else too. Like having a specific number of resource x, or pop number >x or having at least x cities or having a specific legacy trait, etc.

Then comes the choice with the effect:

I made it instant to make the unlock stick. The other stuff is not really event related but whatever you want to unlock, so I do not cover them here.

And maybe a dev can answer two questions from me that cropped up for me:

- the SimulationEvent_TechnologyCompleted seems to do nothing (it will not trigger). Did I just use it wrong or not implemented (or obsolete?)

- the simulationEvent_NewTurnBegin does not do anything either it seems. So same as above?