OpenXcom Forum

Modding => OpenXcom Extended => Topic started by: Meridian on July 18, 2019, 03:27:53 pm

Title: [Documentation] Mana
Post by: Meridian on July 18, 2019, 03:27:53 pm
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]
  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]
  - 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]
  - 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]
        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]
  - type: STR_PISTOL
    manaRequired: true  # default false
      time: 18          # 18% of TU
      mana: 10          # 10 mana points
      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]
      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]
      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]
  - type: STR_SOLDIER
      tu: 50
      stamina: 40
      mana: 25           # minimum starting mana pool 25
      mana: 50           # maximum starting mana pool 50
      mana: 150          # maximum possible mana pool up to 150

4.2 Other units

Code: [Select]
      tu: 54
      stamina: 90
      mana: 100          # mana pool = 100 (+/- global difficulty-based stat adjustment, see below)

Code: [Select]
  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.

Code: [Select]
  STR_NOT_ENOUGH_MANA: "Not Enough 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"
Title: Re: [Documentation] Mana
Post by: Meridian on July 18, 2019, 03:28:06 pm

There will be some screenshots here eventually; for now look here:,6570.msg114780.html#msg114780
Title: Re: [Documentation] Mana
Post by: Finnik on July 18, 2019, 04:16:20 pm
It is very cool! Nice work, I like it!  :)
Title: Re: [Documentation] Mana
Post by: The Reaver of Darkness on September 01, 2019, 03:49:32 am
I have to say this particular documentation was done very well! I am not at all confused!
Title: Re: [Documentation] Mana
Post by: krautbernd on September 01, 2019, 10:12:59 am
Is it possible to replenish mana on a per-item basis (same as with medkits/stimulants for energy)? Can we have mana potions?
Title: Re: [Documentation] Mana
Post by: Meridian on September 01, 2019, 10:24:15 am
Is it possible to replenish mana on a per-item basis (same as with medkits/stimulants for energy)? Can we have mana potions?

Title: Re: [Documentation] Mana
Post by: The Martian on September 01, 2019, 12:53:56 pm
Wow, this is really exciting!

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