[Documentation] Mana

[Meridian]

1. Introduction
--------------------
Mana is a new consumable resource (similar to time units, energy, health, stun and morale).

Each soldier/unit type can have a "mana pool" (attribute), which is the maximum amount of mana it can have.
Each soldier/unit on a battlefield has "mana" (resource), which is the resource itself.

By default, the mana does not regenerate during the battle.
And by default, the mana fully replenishes after the battle.
Both of these features are however configurable and the modder can change them.

The mana (and also the mana pool) can be used in various formulas
(e.g. use cost, damage bonus, accuracy, regen, etc.), same as other resources and other attributes.

Mana pool is constant by default, but can be configured to be trainable.
The training can be primary (same as firing accuracy for example) or secondary (same as strength for example); or even both.


2. Global variables
--------------------

Code: [Select]

mana:
  enabled: false
  battleUI: false
  unlockResearch: STR_SORCERY     # empty by default
  trainingPrimary: false
  trainingSecondary: false
  replenishAfterMission: true

2.1 Enabling/disabling GUI stuff
--------------------

First 3 settings define if the mana as a feature is enabled at all.
By default, it is turned off (on the GUI) and you won't see it anywhere.
Note that these settings are mostly GUI-related, most of the mana game mechanics work regardless of that.

"enabled" setting:
- a global switch, turns most of the GUI display on/off
- affects: Soldier Info screen, Unit Info screen, Debriefing screen, Battlescape UI, Soldier Transform screen and others

"battleUI" setting:
- affects only the Battlescape UI (gives you the option to turn the display off just on this GUI, and keep it everywhere else)

"unlockResearch" setting:
- works similar to "psiUnlockResearch" setting used for Psi strength/skill
- until the research is discovered, the value of the mana pool is unknown to the player (and weapons that require mana cannot be used by XCOM, aliens/civilians are not affected by this)
- by default it's empty, which means it's available from the start of the game

2.2 Tweaking global mana mechanics
--------------------

The other 3 attributes define the mana mechanics.

"trainingPrimary" setting:
- if turned on, mana pool can be increased by gaining direct mana experience during the mission
- the weapons can give mana experience using the "manaExperience" attribute
- formula for converting experience points to stat increase is the same as for firing accuracy

Code: [Select]

items:
  - type: STR_PISTOL
    manaExperience: 250    # this means 2 mana experience points + 50% chance for a 3rd exp point (on every hit on hostile unit)

"trainingSecondary" setting:
- if turned on, mana pool can be increased by gaining any experience during the mission
- formula for stat increase is the same as for strength

"replenishAfterMission" setting:
- if turned on (default), mana fully replenishes after the battle
- if turned off, mana does not replenish automatically and needs to be regained in specialized base facilities
- soldier with missing mana can still go into a battle, but will start only with his current amount of mana (i.e. not full)

Code: [Select]

facilities:
  - type: STR_MAGE_GUILD
    manaRecoveryPerDay: 3

This setting would mean that any base which has a mage guild regenerates 3 points of mana for every (not wounded) soldier in the base per day.
The facility setting is NOT cumulative, more facilities don't provide more regen.
If there are multiple facilities of different type with different regen rate, the best (highest) regen rate is used.


3. Local variables
--------------------

3.1 Mana recovery per turn (armor based)
--------------------

Code: [Select]

armors:
  - type: STR_POWER_SUIT_UC
    recovery:
      mana:
        mana: 0.1           # 10% of total mana pool
        manaCurrent: 0      #  0% of current mana
        manaNormalized: 0   #

On armor level, the modder can define mana recovery each turn (similar to tu/energy/hp/stun/morale recovery).
By default, there is no recovery.
The example above replenishes 10% of total mana pool as mana each turn.

3.2 Mana usage (item based)
--------------------

Code: [Select]

items:
  - type: STR_PISTOL
    manaRequired: true  # default false
    costSnap:
      time: 18          # 18% of TU
      mana: 10          # 10 mana points
    flatSnap:
      time: false       # % cost
      mana: true        # flat cost

The example above shows how to configure mana cost requirements.
"manaRequired" means that the weapon cannot be used until the mana unlock research is discovered.
The cost attributes now support also the "mana" attribute.
The example above means firing a snap shot from a pistol costs 18% of TU and 10 mana points.

3.3 Using mana in other formulas
--------------------

You can use mana in other formulas in OXCE; basically in all formulas which already support usage of let's say energy and stamina.
For example on armors: psiDefense, meleeDodge, resource recovery (tu, energy, hp, stun, morale, mana)
Or on items: damageBonus, meleeBonus, accuracyMultiplier, meleeMultiplier, throwMultiplier, closeQuartersMultiplier

Code: [Select]

items:
  - type: STR_PISTOL_CLIP
    damageBonus:
      mana: 0.0
      manaCurrent: 1.0         # 100% of current mana
      manaNormalized: 0.0

Example above shows how to increase of power of the pistol by the current amount of soldier's mana.

3.4 Damage done to mana (mana burn)
--------------------

As you probably know damage doesn't affect only victim's HP, it can affect many other things as well, including mana.

Code: [Select]

items:
  - type: STR_PISTOL_CLIP
    damageAlter:
      ToHealth: 0.5        # 50% damage goes to health loss
      ToMana: 0.5          # 50% damage goes to mana loss
      RandomMana: false    # mana loss is not randomized


4. Defining starting mana pool, and training caps
--------------------

4.1 Soldiers
--------------------

Code: [Select]

soldiers:
  - type: STR_SOLDIER
    minStats:
      tu: 50
      stamina: 40
      mana: 25           # minimum starting mana pool 25
      ...
    maxStats:
      ...
      mana: 50           # maximum starting mana pool 50
      ...
    statCaps:
      ...
      mana: 150          # maximum possible mana pool up to 150
      ...

4.2 Other units
--------------------

Code: [Select]

units:
  - type: STR_SECTOID_MEDIC
    stats:
      tu: 54
      stamina: 90
      mana: 100          # mana pool = 100 (+/- global difficulty-based stat adjustment, see below)
      ...


Code: [Select]

statGrowthMultipliers:
  tu: 4
  stamina: 4
  ...
  mana: 6                # mana pool on Superhuman (4) would be 124 = 100 + 4*6

Note that non-soldier units always start with full mana!
This is obvious for aliens/civilians, but keep in mind it also applies to xcom HWPs (regardless of the "replenishAfterMission" setting).


5. Yankes-scripts
--------------------

The mana pool of (geoscape/battlescape) soldiers and other units is exposed to scripts.

The current mana of (battlescape) soldiers and other units is exposed to scripts.

The missing mana of (geoscape) soldiers is exposed to scripts.

The "to_mana" damage distribution variable is exposed to DamageUnit script.


6. Other
--------------------

Try not to misuse this feature for completely unrelated stuff... or I will not have much motivation to continue with other features.

If you see improvement potential, speak up.

Translations:

Code: [Select]

  STR_MANA: "MANA"
  STR_MANA_POOL: "MANA POOL"
  STR_MANA_MISSING: "MANA MISSING"
  STR_MANA_RECOVERY: "MANA RECOVERY> {ALT}{0}"
  STR_NOT_ENOUGH_MANA: "Not Enough Mana!"
  STR_MANA_ABBREVIATION: "MAN"
  STR_MANA_CURRENT: "CURRENT MANA"
  STR_MANA_NORMALIZED: "NORMALIZED MANA"
  STR_COST_MANA: "mana"
  manaExperience: "Mana experience"
  manaRequired: "Mana required?"
  ToMana: "Mana dmg multiplier"
  RandomMana: "Mana dmg RNG?"
  mana: "Mana"
  manaRecoveryPerDay: "Mana per day"


[Meridian]

<reserved>

There will be some screenshots here eventually; for now look here: https://openxcom.org/forum/index.php/topic,6570.msg114780.html#msg114780

[Finnik]

It is very cool! Nice work, I like it! 

[The Reaver of Darkness]

I have to say this particular documentation was done very well! I am not at all confused!

[krautbernd]

Is it possible to replenish mana on a per-item basis (same as with medkits/stimulants for energy)? Can we have mana potions?

[Meridian]

Is it possible to replenish mana on a per-item basis (same as with medkits/stimulants for energy)? Can we have mana potions?

yes

[The Martian]

Wow, this is really exciting!

Thank you for adding this feature I can't wait to mess around with it. ^_^

[Nord]

Hi. What commands can be used in script to take current mana to variable and to set current mana from variable? Thanks.

[Meridian]

Hi. What commands can be used in script to take current mana to variable and to set current mana from variable? Thanks.

on a BattleUnit:
- getMana
- getManaMax
- setMana

[Nord]

Thanks. Now my mana shield works.

[eXalted]

Is there a percentage-based ruleset available for stat strings?

Currently, I want to mod into my X-Com files game stat strings for agents with Readiness (the mana resource in XCF) below 50%?

[Bobit]

Is there a percentage-based ruleset available for stat strings?

Currently, I want to mod into my X-Com files game stat strings for agents with Readiness (the mana resource in XCF) below 50%?

https://www.ufopaedia.org/index.php?title=Statstrings

No there is not. Just assume your soldiers have the highest max readiness, then you will only get false negatives.

[memmaker]

Is there a percentage-based ruleset available for stat strings?

Currently, I want to mod into my X-Com files game stat strings for agents with Readiness (the mana resource in XCF) below 50%?

I did propose StatStrings which can read scripted Tags. They would allow such things.
It is already implemented and would just need some lobbying amongst modders.

[Gliks]

can we enable mana depletion = death?

mana as a resource seems more robust than health (more customizable). would like to just replace health entirely and work off of mana

[ohartenstein23]

Health is just as customizable as mana, no need to replace it. There's plenty you can do with HP between scripts, regeneration tags on armor, use costs on items, and recovery from facilities at base.

Mana should be used as a battlescape resource that isn't tied to death (HP), movement (energy), and panicking (morale). If you want something tied to those, use the one that matches and check what can be done by rulesets already and by scripting.