Skip to content
Tirlititi edited this page Jul 28, 2023 · 13 revisions

The NCalc C# library provides a way to use flexible formulas for some options instead of constant values. With Memoria, NCalc formulas can be used in various situations, for mods but also as options for regular players.

Table of Contents

Basic operations

People used to programming should find their bearings. Here are a couple of basic informations so that even people without programming knowledge can use them.

The usual arithmetical operations +, -, * (multiplication) and / can be used. The later one can be either the floating-point division or the integral division when both operands are integers (the result of the division is rounded down in order to keep it as an integer). For example, 5.0 / 2 evaluates to 2.5, in contrast with 5 / 2 that evaluates to 2.

The less-known modulo operation % can also be used. It is basically the remainder of a division.

Comparisons are done with the operations < (strictly less than), <= (less than or equal to), > (strictly greater than), >= (greater than or equal to), == (equals) and != (not equal to). The result of these operations are booleans (true or false).

Boolean operations are ! (unary negation), && (and) and || (or). Booleans can be used even for purely numerical purposes for creating discriminating formulas with the use of the conditional statement {condition} ? {formula 1} : {formula 2} that first checks the boolean condition and uses the formula 1 if the condition is satisfied or the formula 2 otherwise.
For example, the default INI option [Battle] StatusTickFormula uses a conditional statement:
StatusTickFormula = OprCnt * (IsNegativeStatus ? 4 * TargetSpirit : 4 * (60 - TargetSpirit))
For negative statuses (Poison and Venom), the tick formula is thus OprCnt * 4 * TargetSpirit while it is OprCnt * 4 * (60 - TargetSpirit) for the concerned positive status (Regen).
The syntax if({condition}, {formula 1}, {formula 2}) can also be used with the same effect.

Additionally, you can use the bitwise operations ~ (bitwise negate), & (bitwise and), | (bitwise or), ^ (bitwise xor), << (left shift) and >> (right shift). When using bitwise operations, the underlying type of the operands is 'unsigned integer on 32 bits'.

Finally, you can use string operations, in specific situations. Constant strings must be enclosed within single quotes ' (eg. 'My message') and NOT double quotes ". Strings can be compared with the operations == (equals) and != (not equal to) and they can be concatenated with the operation +.

Accessible variables and functions

Math functions

These can be used in any NCalc formula.

Function Description
Min(x, y)
Max(x, y)
The minimum or maximum between two numbers
Abs(x)
Sign(x)
Round(x)
Floor(x)
Ceiling(x)
The absolute, sign (either -1, +1 or 0), rounded, rounded down or rounded up values
Pow(base, x)
Exp(x)
Log(x, base)
Log10(x)
Sqrt(x)
Analytic functions
Cos(x)
Sin(x)
Tan(x)
Acos(x)
Asin(x)
Atan(x)
Trigonometric functions
GetRandom(x, y)
GetRandom()
A random number between x (inclusive) and y (exclusive)
Without arguments, it returns a random byte, that is the same as GetRandom(0, 256)
GetRandomBit(x) A random bit picked in a binary number

Shared informations

These can be used in any NCalc formula.

Constants

Type Examples
CharacterId CharacterId_Zidane, CharacterId_Vivi, CharacterId_Garnet, CharacterId_Steiner, CharacterId_Freya, CharacterId_Quina, CharacterId_Eiko, CharacterId_Amarant, CharacterId_Cinna, CharacterId_Marcus, CharacterId_Blank, CharacterId_Beatrix
BattleCommandId BattleCommandId_Attack, BattleCommandId_Steal, BattleCommandId_Item, BattleCommandId_SummonGarnet...
BattleAbilityId BattleAbilityId_Void, BattleAbilityId_Cure, BattleAbilityId_Cura, BattleAbilityId_Curaga...
RegularItem RegularItem_Hammer, RegularItem_Dagger, RegularItem_MageMasher, RegularItem_MythrilDagger...
TetraMasterCardId TetraMasterCardId_Goblin, TetraMasterCardId_Fang, TetraMasterCardId_Skeleton, TetraMasterCardId_Flan...
EffectElement EffectElement_Fire, EffectElement_Cold, EffectElement_Thunder, EffectElement_Earth, EffectElement_Aqua, EffectElement_Wind, EffectElement_Holy, EffectElement_Darkness
CharacterCategory CharacterCategory_Male, CharacterCategory_Female, CharacterCategory_Terra, CharacterCategory_Gaia, CharacterCategory_Subpc
EnemyCategory EnemyCategory_Humanoid, EnemyCategory_Beast, EnemyCategory_Devil, EnemyCategory_Dragon, EnemyCategory_Undead, EnemyCategory_Stone, EnemyCategory_Soul, EnemyCategory_Flight
BattleCalcFlags BattleCalcFlags_Miss, BattleCalcFlags_Dodge, BattleCalcFlags_MpAttack, BattleCalcFlags_Absorb, BattleCalcFlags_TrueFB, BattleCalcFlags_FalseFB, BattleCalcFlags_Guard, BattleCalcFlags_DirectHP, BattleCalcFlags_AddStat
CalcFlag CalcFlag_HpAlteration, CalcFlag_HpRecovery, CalcFlag_Critical, CalcFlag_MpAlteration, CalcFlag_MpRecovery, CalcFlag_HpDamageOrHeal, CalcFlag_MpDamageOrHeal

Variables and properties

Keyword Description
Gil
GameTime
ScenarioCounter
Self-explanatory
FrogCount The number of frogs Quina caught
StealCount The number of successful steals (whoever player character performed the steal)
EscapeCount The number of successful flees (either way)
BattleCount The number of battles started
StepCount Unused / dummied
TonberryCount The number of Tonberries killed
TetraMasterWinCount
TetraMasterLossCount
TetraMasterDrawCount
TetraMasterCardCount
TetraMasterPlayerPoints
The different Tetra Master related stats
BattleId The numerical ID of the current battle (*)
FieldId The numerical ID of the current field or the latest visited field
CurrentPartyAverageLevel The average level of the fighting party members
It can equally be used in or out of battles
It is a floating-point number
CurrentPartyCount The total number of player characters in the battle (*)
CurrentEnemyCount The total number of enemies in the battle (*)
CurrentTargetablePartyCount The number of targetable player characters in the battle (*)
It rules out Freya when she's in the air or hidden characters before they show up (like Blank against Plant Brain)
CurrentTargetableEnemyCount The number of targetable enemies in the battle (*)
IsRandomBattle Whether the current battle is a random battle (excluding friendly and Ragtime encounters) (*)
IsFriendlyBattle Whether the current battle is a friendly battle (*)
IsRagtimeBattle Whether the current battle is a Ragtime encounter (*)
IsBattlePreemptive
IsBattleBackAttack
Whether the current battle started as a preemptive or a back attack (*)
IsGarnetDepressed Whether Garnet is in a depression state
BattleBonusAP The AP given by the current battle (*)
UseSFXRework Whether the SFX Rework system is activated or not
(*) Out of battles, these values are not expected to be any meaningful.

Functions

Function Description
GetAbilityUsageCount(n) The number of times an ability has been used by a player character (eg. GetAbilityUsageCount(BattleAbilityId_Cure))
GetItemCount(n) The number of items in the player's inventory (eg. GetItemCount(RegularItem_Ore))
GetPartyMemberLevel(n) The level of the n-th party member, with n between 0 and 3 inclusively
GetPartyMemberIndex(n) The character ID of the n-th party member
Note: not currently working correctly but you can use Abs(GetPartyMemberIndex(n)) instead to avoid a bug
GetCategoryKillCount(n) The number of defeated enemies of a given category
Categories are Humanoid (0), Beast (1), Devil (2), Dragon (3), Undead (4), Stone (5), Soul (6) and Flight (7)
Since an enemy can be of multiple categories or of no category at all, the sum of these kill count does not represent the total number of enemies defeated
GetModelKillCount(n) The number of defeated enemies of a given model ID
Best used with arguments like TargetModelID or CasterModelID
GetEventGlobalByte(n) The value of a gEventGlobal entry (called "general variables" in Hades Workshop), which may correspond to a whole lot of different things
CheckAnyStatus(x, y) Check if two status sets share a status in common
Same as (x & y) != 0
CheckAllStatus(x, y) Check if the first status set contains all the statuses of the second status set
Same as (x & y) == y
CombineStatuses(x, y) Combine multiple status sets
Same as x | y
RemoveStatuses(x, y) Remove the second status set from the first one
Same as x & ~y
HasKilledCharacter(killer, character) Whether the battle unit is has KO'ed the character
The killer is identified by its battle ID
The character is identified by its character ID
Eg. HasKilledCharacter(CommandTargetId, CharacterId_Vivi)
Cannot be used out of battles
BattleFilter(basis, playerFilter, targetableFilter, statusFilter) The list of battle units identified with basis, filtered out with different filters
Eg. BattleFilter(CommandTargetId, 1, 1, BattleStatus_Zombie) represents the targets of the context's command that are targetable player characters under the status Zombie

Player character informations

These can be used in NCalc formulas concerning a player character, not necessarily in battles.

Keyword Description
Name The character's name, as a string
Beware that it is language-dependant (besides it can be modified by the player): it should only be used if really the name is the relevant information
Most of the time, better use CharacterIndex
HP
MP
MaxHP
MaxMP
Level
Exp
Speed
Strength
Magic
Spirit
Defence
Evade
MagicDefence
MagicEvade
PlayerStatus
PlayerPermanentStatus
Self-explanatory
CharacterIndex The character's ID
PlayerCategory The character's player category
MPCostFactor The percentage-based multiplier for the character's MP cost, which is 100 by default and eg. 50 with "Half MP"
SerialNumber The character's serial number, which is a more precise information than the character's ID
WeaponShape The icon shape of the equipped weapon
WeaponId
HeadId
WristId
ArmorId
AccessoryId
The item ID of the character's current equipment
MaxHPLimit
MaxMPLimit
MaxDamageLimit
MaxMPDamageLimit
The HP / MP / damage limits
HasSA(n) Whether the character has a supporting ability enabled or not

Battle unit informations

These can be used in NCalc formulas concerning one or multiple units in battles. In several cases, these keywords should be prefixed in order to precise which unit exactly is concerned. For example, in the context of an ability usage, one should use CasterHP to refer to the caster's current HP and TargetHP for the target's.

Keyword Description
Name
HP
MP
MaxHP
MaxMP
Level
Exp
Speed
Strength
Magic
Spirit
Defence
Evade
MagicDefence
MagicEvade
PlayerCategory
MPCostFactor
CharacterIndex
SerialNumber
WeaponShape
WeaponId
HeadId
WristId
ArmorId
AccessoryId
MaxDamageLimit
MaxMPDamageLimit
HasSA(n)
Same as in the player character section
ATB
MaxATB
CurrentStatus
PermanentStatus
ResistStatus
HalfElement
GuardElement
AbsorbElement
WeakElement
BonusElement
WeaponPower
WeaponRate
WeaponElement
WeaponStatus
WeaponCategory
IsPlayer
InTrance
Self-explanatory
Trance The trance gauge's progress, between 0 and 255
Row It is 0 for player characters in back row, 1 front row and 2 for the enemies
Position Player characters have a position between 0 and 3 from right to left, while enemies have a position between 4 and 7 (usually but not always sorted from right to left)
SummonCount The number of times the unit used a summoning command in the current battle
IsSlave For special enemies attached to a "master" enemy
By default, it only concerns the Sand Golem's core, Kraken's tentacles and the duplicated Movers.
IsOutOfReach Whether an enemy is out of reach
By default, it only concerns Ozma when the friendly monster sidequest has not been done
Category The enemy categories
Player characters are flagged as "Humanoid" only
IsStrengthModified
IsMagicModified
IsDefenceModified
IsEvadeModified
IsMagicDefenceModified
IsMagicEvadeModified
These flags are set on by multiple abilities (eg. Power Break)
IsAlternateStand Enemies and morphed player characters may have two battle stances
For example, Black Waltz 3 can either be on the ground or flying in the air; other bosses like Taharka or Ralvuimago have a defensive stance
CriticalRateBonus A special percentage bonus that increases the critical rate by the unit
CriticalRateWeakening A special percentage bonus that increases the critical rate for the attacks targeting the unit
ModelId The unit's model numerical ID
BonusExp
BonusGil
BonusCard
The rewards given by the enemy when defeated
CanUseAbility(n) Check if the player ability could be used by the player in the command menu, ie. it appears in some of their menu and it is not greyed (because of Silence or of its MP cost, etc...)

Command informations

These can be used in NCalc formulas concerning an unit command in battles, either queued or currently performing.

Keyword Description
CommandId The command ID
AbilityId The ability ID
ScriptId
Power
AbilityStatus
AbilityElement
SpecialEffectId
TargetType
AbilityCategory
AbilityFlags
MPCost
The ability's stats
AbilityElementForBonus Mostly the same as AbilityElement, but the ability's elemental affinity on the target can be changed independantly from the bonus it gets from caster's elemental bonuses (eg. "Mag Elem Null" removes spell elements but keeps the elemental bonus they may get)
ItemUseId The item used by the commands Items, Throw or AutoPotion (no item for the other commands)
WeaponThrowShape The icon shape of the item used by a Throw command (otherwise defaults to -1)
IsATBCommand Whether the command is the caster's ATB command and not a counter or any other specially triggered command
IsAbilityMultiTarget Whether the ability can be single-multi targets and is indeed casted in multi-target mode (and thus is susceptible to damage or hit rate reduction)
IsShortSummon Whether the ability is a summon and has been decided to be casted as its short version
IsSpellReflected Whether the command is currently in a reflect state, that is all its current targets are the targets on which the spell was reflected to
IsCovered Whether the attack is deflected to a party member covering their ally
IsDodged Whether the ability has been dodged (which can be known only after the ability hitted)
IsShortRanged By default, it concerns all the enemy abilities and the Attack command of player characters when they use short-ranged weapons
When using the INI option [Battle] CustomBattleFlagsMeaning = 1, it concerns abilities that are flagged as "Contact attack"
IsReflectNull Whether the command ignores Reflect
IsMeteorMiss A special flag for Vivi's Meteor that can be enabled randomly and make Meteor miss
IsCounterableCommand Whether the command is counterable by the game's default standards, ie. when the command ID is out of the "boundary check" commands: it corresponds to the commands that are declared in Commands.csv
CommandTargetId The command's targets as a bit-flags
CommandTargetCount The command's number of targets
CalcMainCounter The number of time the ability applied its effect already, for custom multi-hit abilities

Ability effect informations

These can be used in NCalc formulas concerning an ability at the moment its effect is applied to each of its targets. Formulas that can use these informations can also automatically access to command informations.

Keyword Description
HPDamage
MPDamage
EffectTargetFlags
CasterHPDamage
CasterMPDamage
EffectCasterFlags
The effect's damage and damaging flags
Attack
AttackPower
DefencePower
StatusRate
HitRate
Evade
The effect's intermediate variables, usually computed at the start of battle scripts and used at the end in the formulas of the final HPDamage and such
EffectFlags The effect's special flags
FigureInfo The target's figure infos, which determines what kind of message will appear at the "figure point" (some kind of damage number and/or other messages)
IsDrain Whether the effect is flagged as a drain, and thus will transfer the HP/MP to the caster (or from the caster if the effect actually heals the target)
ReflectFactor The number of reflecting occurrences on the current target, when a spell was reflected by multiple characters on the same unit (0 if the current target was part of the initial target group)
DamageModifierCount The counter of damage modifiers applied to the effect, for scripts that use damage modifiers
It is a positive number when there are more bonuses than penalties; it is a negative number when there are more penalties than bonuses
StatusesInflicted The statuses inflicted by the effect so far
TranceIncrease The increase of target's trance ifever it is applicable (when it is not - because the target doesn't have trance, or it is blocked or the caster is an ally of the target... -, this value may still be positive but it is ignored anyway)
ItemSteal The item that has been stolen

Battle bonus informations

These can be used in NCalc formulas concerning battle rewards.

Keyword Description
BonusAP
BonusCard
BonusExp
BonusGil
BonusItem1
BonusItemCount1
BonusItem2
BonusItemCount2
... up to 6 items
The different battle rewards

World Map informations

These can be used in NCalc formulas used in the context of a World Map, which are only the formulas in StreamingAssets/Data/World/Environment.txt.

Keyword Description
WorldDisc Either 1 or 4 depending on the current World Map's prototype (WorldDisc is normally 1 until the end of the Terra events, after which it is 4)

Specific usage

INI options

NCalc formulas can be used for stat progressions, some status effect formulas and custom battle message formatting in Memoria.ini.

Section Options Accessible informations
[Battle] SpeedStatFormula Player character informations, SpeedBonus and SpeedBase
[Battle] StrengthStatFormula Player character informations, StrengthBonus and StrengthBase
[Battle] MagicStatFormula Player character informations, MagicBonus and MagicBase
[Battle] SpiritStatFormula Player character informations, SpiritBonus and SpiritBase
[Battle] MagicStoneStockFormula Player character informations, MagicStoneBonus and MagicStoneBase
[Battle] StatusDurationFormula
StatusTickFormula
Battle unit informations (with prefix Target or Inflicter), StatusIndex, IsPositiveStatus, IsNegativeStatus, ContiCnt and OprCnt
[Battle] TranceDecreaseFormula Command informations and Battle unit informations (with no prefix)
[Interface] BattleCommandTitleFormat Command informations, Battle unit informations (with prefix Caster) and CommandTitle
[Interface] BattleDamageTextFormat
BattleRestoreTextFormat
BattleMPDamageTextFormat
BattleMPRestoreTextFormat
Battle unit informations (with prefix Target), BaseText, DamageValue and HealValue

Ability features

NCalc formulas are the basis of supporting ability features and active ability features in StreamingAssets/Data/Characters/Abilities/AbilityFeatures.txt.

Section Type Accessible informations
SA Permanent Player character informations
SA BattleStart Only shared informations
SA BattleResult Player character informations, Battle bonus informations, Status, IsFlee, IsFleeByLuck and FleeGil
SA StatusInit Battle unit informations (with no prefix)
SA Command Command informations, Battle unit informations (with no prefix),
Possibly Battle unit informations with prefix Caster but not in conditions and only if IsCasterWellDefined is true,
possibly Battle unit informations with prefix Target but not in conditions and only if IsSingleTarget is true,
IsCasterWellDefined, IsSingleTarget, IsTargeted, IsTheCaster, IsSelfTarget, IsAllyOfTarget, IsAllyOfCaster, IsEnemyOfTarget, IsEnemyOfCaster, AreCasterAndTargetEnemies and AreCasterAndTargetAllies
SA Ability Ability effect informations, Command informations and Battle unit informations (with prefix Caster or Target)
AA Patch Player character informations
AA Priority
GilCost
ItemRequirement
Power
HitRate
Element
Status
Target
SpecialEffect
Command informations, Battle unit informations (with prefix Caster), IsSingleTarget, IsSelfTarget, AreCasterAndTargetEnemies and AreCasterAndTargetAllies

SFX Sequence

NCalc formulas can be used in different arguments of custom battle SFX sequences in .seq files.

Context Accessible informations
Condition of RunThread Command informations, Battle unit informations (with prefix Caster or Target), IsSingleTarget, AreCasterAndTargetsEnemies, AreCasterAndTargetsAllies, IsSingleSelectedTarget, AreCasterAndSelectedTargetsEnemies, AreCasterAndSelectedTargetsAllies, SFXUseCamera, IsAttackHeal, IsAttackCritical, IsAttackMiss, IsAttackKill, IsAttackGuard, AttackDamage and AttackMPDamage
MatchingCondition({formula}) of a character argument Battle unit informations (with prefix Caster or with no prefix), IsTargeted and IsTheCaster

Battle voice

NCalc formulas can be used for ambiant voice acting in BattleVoiceEffects.txt.

Type Accessible informations
BattleInOut Battle unit informations (with no prefix)
Act Command informations, Battle unit informations (with no prefix) and possibly Ability effect informations (only in WhenHitEffect moment)
Hitted Command informations, Battle unit informations (with no prefix) and Ability effect informations
StatusChange Battle unit informations (with no prefix)

Other usage

Context Accessible informations
Entry BattleParameterFormula of CharacterParameters.csv Player character informations
Activation condition of a World Map effect in Environment.txt World Map informations
In parametric movements of custom SFX models .sfxmodel Coordinates CasterPositionX, CasterRootX, CasterMainX, CasterWeaponX, CasterAngleX (+ the same for the coordinates Y and Z), CasterRadius, CasterIsPlayer (+ the same for Target), TargetAveragePositionX, TargetAveragePositionY, TargetAveragePositionZ and Parameter0, Parameter1... (depending on the configured emission parameters)