[DONE][Suggestion] Access to object counters within Arc/Mission/Event scripts

[Meridian]

All 3 script types now have access to 3 different kinds of counters:

1. mission script `varName` counter... you can find it under `alienStrategy:` in the save file

2. global object counter... you can find it under `ids:` in the save file
- this contains the number of various generated game objects, most notably mission markers

3. custom global object counter... this is also under the same `ids:` in the save file
- this contains modder-defined counters, that can increase or decrease after mission success/failure/despawn

The `varName` can be accessed via `missionVarName`.
Global counters (both default and custom) can be accessed via `missionMarkerName`.

The counter is then compared against the limits defined via `counterMin` and `counterMax`.

IMPORTANT: please note that `ids:` in the save file hold a value of the counter plus 1. For example if the game generated 2 terror site, the save will contain `STR_TERROR_SITE: 3`.

Example for an event script (same syntax is valid for mission scripts and arc scripts):

Code: [Select]

eventScripts:
  - type: STR_TEST
...
    missionVarName: shippingLanes           # varName from mission scripts
    missionMarkerName: STR_TERROR_SITE      # marker name from alien deployment
    missionMarkerName: CUST_TERROR_SUCCESS  # custom counter name from alien deployment
    counterMin: 3
    counterMax: 3                           # -1 = infinity/unlimited
...

Please only use one of the `missionVarName` and `missionMarkerName` at a time; they share the `counterMin` and `counterMax` values.
Default for `counterMin` is 0 (zero).
Default for `counterMax` is -1 (unlimited).

[Meridian]

Custom mission counters are defined via 8 new alienDeployment attributes:
1. `counterSuccess` - increases on mission success
2. `counterFailure` - increases on mission failure and on mission site despawn (which is also a failure, duh)
3. `counterDespawn` - increases on mission site despawn
4. `counterAll` - increases on mission success, failure and despawn

5. `decreaseCounterSuccess` - decreases on mission success
6. `decreaseCounterFailure` - decreases on mission failure and on mission site despawn (which is also a failure, duh)
7. `decreaseCounterDespawn` - decreases on mission site despawn
8. `decreaseCounterAll` - decreases on mission success, failure and despawn

Example:

Code: [Select]

alienDeployments:
  - type: STR_TERROR_MISSION
...
    counterSuccess: CUSTOM_TERROR_SUCCESS
    counterFailure: CUSTOM_TERROR_FAILURE
    counterDespawn: CUSTOM_TERROR_DESPAWN
    counterAll: CUSTOM_TERROR_ALL
...

PS: note that just like the default game object counters, also these custom counters have a value in the save file increased by one... keep that in mind when testing/investigating

PS2: counters cannot decrease below zero

PS3: don't decrease non-custom counters, you'll break/crash the game

[Finnik]

How do you think, can we affect those variables with research discovery?

[Meridian]

It is feasible.
Do you need it?
If yes, do you have any preferences how to do it?

[Finnik]

I do, and I think as researches are a very common way to affect campaign, some other modders might need it as well.

I think `increaseCounter: ALIEN_TECHNOLOGY` and `decreaseCounter: TIME_BEFORE_ALIEN_RAMPAGE` would be nice.

[Finnik]

If anything - I need it for getOneFree as well (actually, mostly for it). Do you want me to code that?

[Meridian]

I have put it on todolist.
It will be added in the next release.

[mutantlord]

Hi, new to the event modding, I like to know if events can spawn a mission via eventscript?

[Finnik]

Nope, but mission can be spawned with mission script 
Tho, you can make the event that would enable conditions for mission script. Traditionally, it can be done with unlocking "hidden" research project (the one without ufopedia and unavailable to the player). Or, ofc, you can make this project visible with attaching pedia article to it. You can spawn item, that would be in turn trigger the mission.

For more complex story, you can use this new counters as triggers, but you can only spawn specific missions from mission scripts or from alien bases.

[mutantlord]

That is a bit complicated for me thanks for the explanation.

[Finnik]

I have put it on todolist.
It will be added in the next release.

Sorry for bothering, but is there any approximate ETA for it?
I will be glad to contribute, if needed 

[Meridian]

in OXCE 7.6

when that is going to happen is not easy to say
earliest end of May
more probably mid June
worst case beginning of July

[Finnik]

OK, thanks for sharing detailed plans! =)

[Meridian]

https://github.com/MeridianOXC/OpenXcom/commit/48569ab0feff4392ff8964259e3d4ec96b0028ea

pls check if this is ok for you

Code: [Select]

research:
  - name: STR_SECTOID_NAVIGATOR
    decreaseCounter: [COUNTER_BBB, COUNTER_EEE]
  - name: STR_SECTOID_SOLDIER
    increaseCounter: [COUNTER_AAA, COUNTER_BBB, COUNTER_CCC]


[Finnik]

That's great. That property is also taken into account on `getOneFree` and other cases where I unlock research (event, deployment), right?