[Example] Handcuffs script

[Yankes]

ups, I forget one thing, spending resources is unconditional BEFORE script is run.
I incorrectly assume that default behavior still have change of charges but it was removed from it.

Code: [Select]

set medikit_action_type 0;
Is only responsible for:
a) Applying default healing or stim or pankilers
b) Updating item usage statistics (like revivedSoldier or appliedStimulant counts)

Spend of charges and costs are done before script unconditionally.

Sorry for confusion.

[Kozinsky]

Spend of charges and costs are done before script unconditionally.

I came to the same conclusion.
But it's strange that the script can affect an item that has run out of charges - in my case, it means that the item disappears from the game. I thought that first the algorithm of using the item is processed, then it disappears from the game after spending all its charge and only then the script starts.
Anyway, my task solution works pretty well.

[krautbernd]

Sometimes - not always - unconscious units become overstunned upon applying handcuffs. Checking the save file, health on these units declines every turn. From what I can tell (by manually reducing health in the save), the unit eventually dies from overstun. There is no way to prevent this in-game, as the stun level can't be reduced and handcuffs can not be removed. This makes applying handcuffs a potential liability.

Is this intended? Mod is XCF btw, but according to Solarius the script should be indentical.

[Kozinsky]

Sometimes - not always - unconscious units become overstunned upon applying handcuffs. Checking the save file, health on these units declines every turn. From what I can tell (by manually reducing health in the save), the unit eventually dies from overstun. There is no way to prevent this in-game, as the stun level can't be reduced and handcuffs can not be removed. This makes applying handcuffs a potential liability.

In examining this case, I concluded that the maximum safety stun level of the wounded creatures (before they begin to suffer damage from overstun) is lower than maxStunLevel. I therefore reduce maxStunLevel by the percentage reduction of the creature's health.
For example, there is a healthy creature with 100 HP and maxStunLevel 200, i.e. when it receives 201 stun level, it will receive damage from overstun.
We will deal 40 damage to this creature and its current health will be 60 HP. In this state the creature will take damage from overstun at (very approximately) 120 stun level.
I have implemented this algorithm in the current version of XCF at GitHub. But I need to run many different tests to make sure that this solution will always work fine.

[krautbernd]

Thanks for the update on this, will wait for next XCF version.

[Dioxine]

1) Is there a standalone version of this script? There's downloads, but not sure how up to date are they. (I'm interested in the version as described in the first posts, with % chances of targets breaking out dependant on their Strength.)
2) Would it be possible to add a text message when the target is getting handcuffed, and when handcuffing failed due to it being immune to that level of handcuffs?
3) Would it be possible to add some indicator that target broke out of handcuffs, ideally by playing a sound?

[ohartenstein23]

Scripts can't play sounds, but text warnings are possible. Probably could do an indicator like colored flashing of the the corpse while handcuffed.

[spawi]

Folks, I was grokking the handcuffs scripts and I think I found up to three possible problems, or I don't get the intent behind the logic. Can you help me understand?

I am talking about these handcuffs scripts:
https://github.com/SolariusScorch/XComFiles/blob/4f8e083df57eeca3a3a1b2dcd455a8ddc30b0cfa/Ruleset/scripts_XCOMFILES.rul#L2150-L2167

               
              else gt RandomValue StrengthLevel;
                unit.getStun CurrStun;
                unit.getStunMax NewStun;
                unit.Stats.getHealth UnitStatHealth;
                unit.getHealth UnitHealth;
               
                muldiv NewStun UnitHealth UnitStatHealth;
                # debug_log "newTurnUnit: unit.Stats.getHealth = " UnitStatHealth ", unit.getHealth = " UnitHealth ", NewStun = " NewStun;
               
                sub CurrStun NewStun;
                add PrevStun CurrStun;
                if lt PrevStun 0;
                  set PrevStun 0;
                end;
                unit.setTag Tag.VIRTUAL_STUN_LEVEL PrevStun;
                unit.setStun NewStun;
                # debug_log "newTurnUnit: if RandomValue (" RandomValue ") > StrengthLevel (" StrengthLevel ") then unit.setTag.VIRTUAL_STUN_LEVEL: " PrevStun ",   unit.setStun: " NewStun;
              end;

The first possible issue I see is that the NewStun, aka "stun-with-handcuffs" aka "stun as understood by the game", is not capped at 200, the same way it is done here:
https://github.com/SolariusScorch/XComFiles/blob/4f8e083df57eeca3a3a1b2dcd455a8ddc30b0cfa/Ruleset/scripts_XCOMFILES.rul#L1860-L1863

This might cause problems for units that have more than 50 base health, because maxStun is base health * 4, as can be seen here:
https://github.com/MeridianOXC/OpenXcom/blob/19449159c806c9e3e57e6907e3580812ff9bacf9/src/Savegame/BattleUnit.cpp#L5224

Thus, for example, if a unit with 100 base health loses 20 hit points, this script will compute its new stun to be (100*4) * (100-20) / 100 = 400 * 0.8 = 360. Ouch.

The second potential problem I see is that the "stun-without-handcuffs" aka "virtual stun" gets set to 4 * (baseHealth - health). Meaning: the more badly wounded the unit, the larger the virtual stun.
This virtual stun is used to compute if the unit will even try to escape the handcuffs. If it is > 0 it won't. This can be seen here:
https://github.com/SolariusScorch/XComFiles/blob/4f8e083df57eeca3a3a1b2dcd455a8ddc30b0cfa/Ruleset/scripts_XCOMFILES.rul#L2134-L2139

For the third problem: this virtual stun sometimes will end up dropping by 1 or 2 by turn, or not at all. Not sure why, but I think these are some rounding errors, as sometimes maxStun is 4*baseHealth-1 or -2.
Thus, some units will never try to escape the handcuffs while some of them will when the stun gets to 0. This is dependent on rounding error.

I deduced the formula for virtual stun from this code fragment:

                sub CurrStun NewStun;
                add PrevStun CurrStun;
                if lt PrevStun 0;
                  set PrevStun 0;

Here CurrStun is initially set to the "stun-including-handcuffs" which is at first MIN(maxStun, 200) which is MIN(baseHealth * 4, 200)
NewStun is maxStun * health / baseHealth

So CurrStun becomes, ignoring he MIN function:
CurrStun = CurrStun - NewStun
which is
maxStun - (maxStun * health/baseHealth)
which is
baseHealth * 4 - (baseHealth * 4 * health/baseHealth)
which is
baseHealth * 4 - (health * 4)
which is
4 * (baseHealth - health)

This now ends up being added to PrevStun which is the "stun-without-handcuffs" a.k.a. virtual stun.

Note that the numbers stabilize in repeated computations in following turns.
Next turn CurrStun will have the value of previous turns' NewStun

Applying to the formula above we get:

CurrStun = CurrStun - NewStun
=>
CurrStun = NewStun - NewStun
=>
CurrStun = 0

As I mentioned, sometimes there are rounding errors and instead CurrStun is -1 or even -2, decreasing the virtual stun by 1 or 2 each turn. But not the "stun-with-handcuffs" aka "stun as understood by the game".