v2k20 moddable adds the ability to load a .txt file for warsim to take events from. For this to work, the data inside the .txt has to be formatted in a way that the interpreter knows what to do with it. This is what this post will be concerned with.

(this tutorial was updated with additional features added in 2022 update)

(0) Introduction

Your event_pack.txt can contain 3 things : (1) comments, which will be ignored by the interpreter (2) "firsts", marked by F:, which will always be loaded first - normally you'd use them to explain how the war started, (3) events and (4) treaties, marked by T:.

Note that each line must end with a ; symbol, just like in Java.

(1) Comments

Comments are opened by /* and closed by */.  Anything inside these will be ignored by the interpreter. You can use them to annotate your event pack, e.g. "/*author : xXNoobSlayerXx*/"

(2) Firsts

Firsts take the shape of "F:" followed by some text; e.g.

F:%state_a% invades %state_b% due to a cookie dispute.;

*%state_a% and %state_b% are examples of variables. When a user using your event pack gets an event with a variable used in the event text, it will be replaced by the actual thing it represents. e.g. %state_a% will be replaced by a name of one of the participating states. Variables can also be used in event texts. Full list of variables the interpreter understands is : 

• %state_a%
• %state_b%
• %rng_power% -- replaced with a random power the user enters on Other Powers screen.
• %st_a_pwr_dif% -- replaced with losses/gains in manpower caused by this event* for state_a. *Will not work for firsts, only for events (since firsts can't make any changes to stats).
• %st_b_pwr_dif%
• %st_a_rng_city% -- replaced with a random city under control of state_a
• %st_b_rng_city%
• %st_a_frontline_city% -- replaced with a city under control of state_a closest to the frontline
• %st_b_frontline_city%
• %state_a_lost_cities_list% -- returns a list of cities originally owned by state a but currently not under its control
• %state_b_lost_cities_list%
• %rng_5% -- will be replaced by a random number in range (0,4]
• %rng_20% -- will be replaced by a random number in range (0,20]
• %rng_50% -- will be replaced by a random number in range (0,50]
• %newline% -- will be replaced by a new line character

Note that state_a and state_b do not directly correspond to state 1 and state 2. Instead, the interpreter decides which state is state_a and which state is state_b during runtime. This allows you to write an event once, without having to copy it switching a and b around.

(3) Events

Events take the shape of

{conditions}event text{range_start,range_end,city_difference][range_start,range_end,city_difference];

(a) Condition is a statement that must be true for your event to occur. Condition can be anything of the form {var1>/</=var2} (no operation symbols other than >,<,= are understood). vars can be either a constant integer, e.g. number 5, or some ingame variable. Variables that can be inserted into conditions are :

• cities_a -- means the number of cities state_a currently controls
• cities_b
• pwrdif_a -- means (manpower of state a) - (manpower of state b)
• pwrdif_b -- means (manpower of state b) - (manpower of state a)
• dev_a -- means the development of state_a the user put in the stats.
• dev_b

Conditions of form {cities_a>cities_b}, {pwrdif_a>-20000} and {dev_a = 4} are all valid conditions. {0} is an empty condition, meaning your event can happen regardless of stats and current situation. You can have multiple conditions by separating them with a comma, e.g. {dev_a>dev_b,cities_a=5}.

(b) The square brackets represent the event effect. The first bracket (left to right) contains effects of the event on state_a. The first two positions are used to randomly generate the number of soldiers lost or gained in that range. The last position can hold either +, - or 0. + means state_a gains a city, - means state_a loses a city and 0 means no changes. Second bracket is the same for state_b.

(4) Treaties

Treaties have the following structure

T:{conditions}text;

They accept exactly the same conditions as the events, and also support multiple conditions. These will be used after the war has concluded, as the treaty text. Note (!) for treaties and treaties only, state_a will always represent the winning state and state_b the losing state.

If the conditions are satisfied for several treaties (or treaties use the empty condition {0}) a random treaty text will be picked from those.

(5) Conclusion

While, I'm sure, the little "language" I came up with seems illogical, I assure you it will become clearer when you look at an example of its use. You can download the std_events.txt used in warsim as "standard event pack" on the front page and poke around or edit it. Feel free to use it as a base for mods/expansions too. Hopefully that helps if someone wants to make something for warsim.

(! please note that the interpreter doesn't do much format checking. It will just skip events it can't interpret, without giving you much feedback. I should probably make some sort of format checker tool.)