-
Notifications
You must be signed in to change notification settings - Fork 51
NCalc formulas
Tirlititi edited this page Jun 29, 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.
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 +.
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 |
These can be used in any NCalc formula.
| 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
|
| 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
Out of battles, this value is not expected to be any meaningful |
| 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
Out of battles, this value is not expected to be any meaningful |
| CurrentEnemyCount |
The total number of enemies in the battle
Out of battles, this value is not expected to be any meaningful |
| 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
Out of battles, this value is not expected to be any meaningful |
| IsGarnetDepressed | Whether Garnet is in a depression state |
| BattleBonusAP |
The AP given by the current battle
Out of battles, this value is not expected to be any meaningful |
| UseSFXRework | Whether the SFX Rework system is activated or not |
| 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
|
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 |
| 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" |
| CharacterIndex | The character's ID |
| 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 as a supporting ability enabled or not |
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...) |
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 |
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 |
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 |
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)
|
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
|
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
|
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
|
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) |
| 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)
|