Event Scripting - Add Variables, Scopes, and Better Conditionals

[11:59 Development Team 253]

Hello; I'm Vis from the 11:59 Development Team. (And, yes, I've come out of the dark to express a few issues I'd hope to raise on behalf of the AOH2 modding community). For those not used to modding, I'll provide a quick glossary.

• Conditionals are what determines when an Event triggers, essentially functioning as an if-statement. If this, then do that.
• Effects are commands that change things about the game. (E.g. province_economy=15.4 is an effect that currently gives a random province 15,4 economy points).
• Scopes determine the game objects for which effects are applied. For example, if France is currently scoped to, all effects are applied at the civilisation level for France; it is a Civilisation Scope.

The Problem.

Currently, from what we know about Events and event scripting (Events.txt), I have numerous concerns about just how flexible modding will be, since the number of effects and conditions appear to be even less than those from AOH2. I understand the file is somewhat old, but here's what are likely missing for modders from my personal understanding.

1. No individual province scope. Modders should be able to select provinces that meet certain conditions. From Events.txt, they currently cannot - they can only target either random provinces, the capital province, or all provinces held by a civilisation. What if I want to target all provinces owned by a civilisation with a specific building? It doesn't appear possible.

2. No variables. There exist boolean 'flags', but this is it. Variables should be able to store numbers, have basic mathematical operations (add, subtract, divide, multiply) and be used in effects, similar to Paradox scripting. Variables should also be able to be assigned at the Province scope.

3. Relative conditionals? Currently, there appears to be no way to determine relative figures - only absolute ones. I'm not sure if this has or will be changed before release, but currently you can only specify hard numbers (e.g. A civilisation has more than 50k manpower), and not percentages (Does a civilisation have more than 50% of their manpower capacity filled? This appears impossible to check from Events.txt).

4. Nested conditionals? This isn't strictly necessary and more QOL, but nested conditionals (i.e. through a limit scope and conditional blocks, like with Paradox) would make Events less tedious and verbose to script, as well as allow for more complex boolean operations. Ideally, this would come in the form of a Limit Scope, which could be applied to options (some Event options could be locked behind a given set of conditions for example).

Proposed Technical Changes.

To make the game genuinely moddable, the following changes should probably be made, especially since people will be scripting Events through text files, rather than editing them from within the game. Anything missing from Events.txt will be marked in red.

1. Scopes. These are central to modding strategy games, and determine the scope, or extent to which effects apply (similar to nesting in programming). Such scopes would include:
   1. Global Scope. Effects/Conditions are applied globally, to all civilisations.
   2. Civilisation Scope. Effects/Conditions are applied to the civilisation as a whole.
   3. Province Scope. Effects/Conditions are applied to a specific province.
2. Variables. This has already been proposed, but I'll try to specify some of the effects that would be necessary for modding.
   1. Setting Number variables. Current variables function as flags or booleans (i.e. true/false), and do not store values.
   2. Basic mathematical operations. (Addition, Subtraction, Multiplication, Division). As an example, these might be expressed as add_variable=dummy_variable=15 (Adds 15 to a dummy variable).
      1. Variables should also be able to be added to, or operate on one another. For example, if a=40, and b=60, then add_variable=b=40 should mean that b=100.
   3. Scoped/Local variables. Instead of simply restricting variables to the Civilisation level, variables should be able to be assigned to Provinces, Civilisations, as well as the Global level. This would allow for modders to have much more flexibility in adding mechanics.
   4. Conditionals. Numeric variables also need conditionals to operate. These should both be able to check against absolute numbers (e.g. is a > 40?), but also against other variables (e.g. is a > b?). This is already in place for most other variables in-game.
   5. Allow Variables to be used in current Effects. Once we can dynamically create and set variables, we should be able to use them in both effects and conditionals (e.g. civ_gold_over=b now checks if civ_gold > b, and gold=b now gives b amount of gold).
3. Civilisation Conditionals. Global-level events have long been requested, and given that they appear to be possible, there should be a way to restrict Events to only firing for Civilisations that meet a given set of conditions.
4. Province Conditionals. What if I want to only target provinces that have a specific building, or provinces with a specific resource? How would I go about doing that? In the current setup, this appears impossible, but there are plenty of good reasons a modder might want to do this. 

Of course, the document on which I based all of this on is quite old, and so I could be wrong about the state of Event Scripting, but this is what I've managed to glean so far. This is open to comment, as always.

- Sincerely, Vis, 11:59 Development Team.

Edited September 12, 2024 by 11:59 Development Team

[Matvey 252]

It would be nice to add the ability to provide some temporary effects through events.
Explanation: conditional event, which for 10 years reduces the cost of infrastructure construction by _ by 10%

or

a conditional event that gives all units -1 attack until the end of a certain war.

You can continue further with all the variables existing in the game,
amenable to change.

[11:59 Development Team 253]

1 hour ago, Matvey said:

It would be nice to add the ability to provide some temporary effects through events.
Explanation: conditional event, which for 10 years reduces the cost of infrastructure construction by _ by 10%

or

a conditional event that gives all units -1 attack until the end of a certain war.

You can continue further with all the variables existing in the game,
amenable to change.

It would be, but I want to try to focus on the fundamentals so far since this is theoretically achievable with current mechanics:

Event 1: Sets price of a dummy resource for X months (this is timed according to Events.txt, you could also use civ_is_at_war_days_over). The only option on this non-displayable event grants the bonus. (-X% Infrastructure Construction Cost)

Event 2: Once the price of a dummy resource falls or a country has been at war with the dummy nation for X months, then trigger a non-displayable event revoking the bonus. (+X% Infrastructure Construction Cost)

 

I think the fact that mechanics like these are the only way you could realistically do this with what's currently in Events.txt tells you how limited it actually is at the current moment, unfortunately.

[Shiite 2,468]

I feel these are very valid concerns that should be addressed @Unity @eNeXPii

[eNeXPii 35]

@11:59 Development Team I saw that issue but need to have hands on the game and current files to see how that can work, but disagree on the options, we just need to see it but the big red flag is there for "future of" events...

Edited September 26, 2024 by eNeXPii