Formula System Conversion
Background
This work is based on:
- Formula Parser Equip Vars Demo based on Formula Parser Equip Vars Proposal which includes Formula Parser-JEP removal (sandbox) and Formula Parser Conversion Instructions
In order to be successful, the following major data changes are needed
- Convert what is today "KEY_Unarmed Strike" into an actual object in the data. Right now this is implied in WEAPONH output token, and that isn't good. This will gate the data team being able to do any conversion on Equipment that may require behaviors on an Unarmed attack (such as CRITMULT conversion)
- Move all Stats/Checks/Alignment out of the game mode and into the PCC files. This will gate the ability of the code team to start to sunset some code and use the formula system internally (and thus make conversion easier)
Considerations
Things to watch out for in any conversion:
- If the BONUS token has trailing PRExxx, then conversion may not be possible without other conversions being done in parallel
- If the BONUS token takes in other variables, then conversion may require other new variables to be created
Conversions
Alternate HP
Past Process
BONUS:HP|ALTHP|...
Replacement
Requires a codeControl.lst file in the game mode. Reminder that the codeControl.lst file takes one token per line.
The codeControl.lst token is:
- ALTHP:x
- "x" in this case is the name of the new formula system variable that contains the alternate HP value.
Effects
If the ALTHP code control is used, then any BONUS:HP|ALTHP will be reported as a "not supported" token. The ALTHP control is either ON (new variable) or OFF (BONUS supported).
The ALTHP export (output system) token will continue to function, and its value is controlled by whether the ALTHP code control is enabled. If not, it uses BONUS, if it is, it uses the new formula provided as the argument to the ALTHP code control.
Of course, the preferred method (since the old output tokens will be deprecated anyway) is to convert the ALTHP export token to use the FreeMarker tokens for new variables:
${pc.val.x}
(again, where the "x" is the new variable now holding alternate HP.
Specific Considerations
None
Face
Past Process
FACE: in Race LST
FACE: in Template LST (overrides Race LST - order is somewhat arbitrary of "what wins")
Replacement
Requires a codeControl.lst file in the game mode. Reminder that the codeControl.lst file takes one token per line.
The codeControl.lst token is:
- FACE:x
- "x" in this case is the name of the new formula system variable that contains the FACE value. It is expected to be an ORDEREDPAIR
Effects
If the FACE code control is used, then any FACE token in Race or Template LST files will be reported as a "not supported" token. The FACE control is either ON (new variable) or OFF (FACE LST token supported).
The FACE export (output system) token will continue to function, and its value is controlled by whether the FACE code control is enabled. If not, it uses FACE. if it is, it uses the new formula provided as the argument to the FACE code control.
Of course, the preferred method (since the old output tokens will be deprecated anyway) is to convert the FACE export token to use the FreeMarker tokens for new variables:
${pc.val.x}
(again, where the "x" is the new variable now holding new FACE).
Specific Considerations
None
Equipment Critical Multiplier (CRITMULT)
Past Process
- CRITMULT: Token in Equipment LST (for primary head)
- ALTCRITMULT: Token in Equipment LST (for secondary head)
- BONUS:WEAPONPROF|CRITMULTADD to alter the critical multiplier
Replacement
Requires a codeControl.lst file in the game mode. Reminder that the codeControl.lst file takes one token per line.
The codeControl.lst token is:
CRITMULT:x
"x" in this case is the name of the new formula system variable LOCAL to EQUIPMENT.PART that contains the CRITMULT value. It is expected to be a NUMBER
Effects
If the CRITMULT code control is used, then any CRITMULT or ALTCRITMULT token in Equipment LST files will be reported as a "not supported" token. The CRITMULT control is either ON (new variable) or OFF (*CRITMULT LST tokens supported).
Any BONUS:WEAPONPROF|CRITMULTADD will also be reported as an unsupported token if the CRITMULT code control is used.
The Equipment CRITMULT Term will also break (not have the correct value)
The CRIT (and ALTCRIT) portions of the export system (output system) will continue to function. This includes portions of the following Export tokens: EQ, EQCONTAINERS, EQCONTAINER, EQCONTAINERW, WEAPON. The Crit Mult values are controlled by whether the CRITMULT code control is enabled. If not, it uses the CRITMULT as generated by the tokens. if it is, it uses the new formula provided as the argument to the CRITMULT code control.
In the long term, the preferred method will be to convert fetching the Critical Multiplier to getting the variable, but this is not currently possible due to lack of ability to do all the export of equipment in the new freemarker system.
Specific Considerations
Check for usage of "CRITMULT" in a formula in any Equipment. If this is used, then the game mode may not be convertable (yet) and/or a temporary variable may need to be created to carry that value in the old calculation system.
Equipment Critical Multiplier (CRITRANGE)
Past Process
- CRITRANGE: Token in Equipment LST (for primary head)
- ALTCRITRANGE: Token in Equipment LST (for secondary head)
- BONUS:EQMWEAPON|CRITRANGEADD to alter the critical range
- BONUS:EQMWEAPON|CRITRANGEDOUBLE to alter the critical range
- BONUS:WEAPONPROF|CRITRANGEADD to alter the critical range
- BONUS:WEAPONPROF|CRITRANGEDOUBLE to alter the critical range
Replacement
Requires a codeControl.lst file in the game mode. Reminder that the codeControl.lst file takes one token per line.
The codeControl.lst token is:
CRITRANGE:x
"x" in this case is the name of the new formula system variable LOCAL to EQUIPMENT.PART that contains the CRITRANGE value. It is expected to be a NUMBER
Effects
If the CRITRANGE code control is used, then any CRITRANGE or ALTCRITRANGE token in Equipment LST files will be reported as a "not supported" token. The CRITRANGE control is either ON (new variable) or OFF (*CRITRANGE LST tokens supported).
Any BONUS shown above will also be reported as an unsupported token if the CRITRANGE code control is used.
The CRITRANGE (and ALTCRITRANGE) portions of the export system (output system) will continue to function. This includes portions of the following Export tokens: EQ, EQCONTAINERS, EQCONTAINER, EQCONTAINERW, WEAPON. The Crit Range values are controlled by whether the CRITRANGE code control is enabled. If not, it uses the CRITRANGE as generated by the tokens. if it is, it uses the new formula provided as the argument to the CRITRANGE code control.
In the long term, the preferred method will be to convert fetching the Critical Range to getting the variable, but this is not currently possible due to lack of ability to do all the export of equipment in the new freemarker system.
Specific Considerations
None
Equipment (Armor) EDR
Past Process
EDR: in Equipment LST
- BONUS:EQMARMOR|EDR to alter the EDR
Replacement
Requires a codeControl.lst file in the game mode. Reminder that the codeControl.lst file takes one token per line.
The codeControl.lst token is:
- EDR:x
- "x" in this case is the name of the new formula system variable that contains the EDR value. It is expected to be a NUMBER
Effects
If the EDR code control is used, then any EDR token in Equipment LST files will be reported as a "not supported" token. The EDR control is either ON (new variable) or OFF (EDR LST token supported).
Any BONUS:EQMARMOR|EDR will also be reported as an unsupported token if the EDR code control is used.
The EDR export (output system) token will continue to function, and its value is controlled by whether the EDR code control is enabled. This includes portions of the following Export tokens: EQ, EQCONTAINERS, EQCONTAINER, EQCONTAINERW, ARMOR. If not, it uses EDR. if it is, it uses the new formula provided as the argument to the EDR code control.
In the long term, the preferred method will be to convert fetching the Critical Range to getting the variable, but this is not currently possible due to lack of ability to do all the export of equipment in the new freemarker system.
Specific Considerations
None
Equipment FUMBLERANGE
Past Process
- FUMBLERANGE: Token in Equipment and EqMod LST
Replacement
Requires a codeControl.lst file in the game mode. Reminder that the codeControl.lst file takes one token per line.
The codeControl.lst token is:
FUMBLERANGE:x
"x" in this case is the name of the new formula system variable LOCAL to EQUIPMENT that contains the FUMBLERANGE value. It is expected to be a STRING
NOTE: This is currently attached to the EQUIPMENT. Ideally, in the future, range will be attached to the EQUIPMENT.PART, but this is necessary for current backward compatibility in places where the Range is used and which are not aware of which PART they are operating upon. Expect a future code control to allow modification of this value to a PART once ToHit and Damage are complete.
Effects
If the FUMBLERANGE code control is used, then any FUMBLERANGE token in Equipment LST files will be reported as a "not supported" token. The FUMBLERANGE control is either ON (new variable) or OFF (*FUMBLERANGE LST tokens supported).
The FUMBLERANGEportions of the export system (output system) will continue to function. This includes portions of the following Export tokens: EQ, EQCONTAINERS, EQCONTAINER, EQCONTAINERW, WEAPON. The FUMBLERANGE values are controlled by whether the FUMBLERANGE code control is enabled. If not, it uses the FUMBLERANGE as generated by the tokens. if it is, it uses the new formula provided as the argument to the FUMBLERANGE code control.
In the long term, the preferred method will be to convert fetching the FUMBLERANGE to getting the variable, but this is not currently possible due to lack of ability to do all the export of equipment in the new freemarker system.
Specific Considerations
None
Creature HANDS
Past Process
- HANDS: in Race and Template LST files
- PREHANDS:
- HANDS (term) in formula system
Replacement
Requires a codeControl.lst file in the game mode. Reminder that the codeControl.lst file takes one token per line.
The codeControl.lst token is:
- CREATUREHANDS:x
- "x" in this case is the name of the new formula system variable that contains the quantity of Hands for the PC. It is expected to be a NUMBER
Effects
If the CREATUREHANDScode control is used, then any HANDS token in Race or Template LST files will be reported as a "not supported" token.
Any PREHANDS: will also be reported as "not supported"
Specific Considerations
Check for usage of "HANDS" in any JEP formula. If this is used, then the game mode may not be convertable (yet) and/or a temporary variable may need to be created to carry that value in the old calculation system.
Creature LEGS
Past Process
- LEGS: in Race and Template LST files
- PRELEGS:
- LEGS (term) in formula system
Replacement
Requires a codeControl.lst file in the game mode. Reminder that the codeControl.lst file takes one token per line.
The codeControl.lst token is:
- LEGS:x
- "x" in this case is the name of the new formula system variable that contains the quantity of Legs for the PC. It is expected to be a NUMBER
Effects
If the LEGS code control is used, then any LEGS token in Race or Template LST files will be reported as a "not supported" token.
Any PRELEGS: will also be reported as "not supported"
Specific Considerations
Check for usage of "LEGS" in any JEP formula. If this is used, then the game mode may not be convertable (yet) and/or a temporary variable may need to be created to carry that value in the old calculation system.
PC & Equipment MAXDEX
Past Process
- MAXDEX: in Equipment LST files
- BONUS:MISC|MAXDEX
- BONUS:EQMARMOR|MAXDEX
- MODEQUIPMAXDEX (term)
Replacement
Requires a codeControl.lst file in the game mode. Reminder that the codeControl.lst file takes one token per line.
The codeControl.lst tokens are:
- EQMAXDEX:x
- PCMAXDEX:x
- "x" in this case is the name of the new formula system variable that contains tha MAXDEX value for the PC or Equipment. It is expected to be a NUMBER
Do NOT only enable one of the two code controls above - use both or neither.
Effects
If the EQMAXDEX and PCMAXDEX code control is used, then any MAXDEX token on equipment will be reported as a "not supported" token.
Any BONUS:MISC|MAXDEX or BONUS:EQMARMOR|MAXDEX will also be reported as "not supported"
The MAXDEX portions of the export system (output system) will continue to function. This includes portions of the following Export tokens: ARMOR, EQ, EQCONTAINERS, EQCONTAINER, EQCONTAINERW, MAXDEX. The MaxDex values are controlled by whether the PCMAXDEX/EQMAXDEX code control is enabled. If not, it uses the MAXDEX as generated by the tokens. if it is, it uses the new formula provided as the argument to the PCMAXDEX/EQMAXDEX code control.
Specific Considerations
Check for MODEQUIPMAXDEX in JEP formulas
Equipment RANGE
Past Process
- RANGE: Token in Equipment LST
- BONUS:EQMWEAPON|RANGEADD to alter the range
- BONUS:EQMWEAPON|RANGEMULT to alter the range
- BONUS:RANGEMULT|* to alter the range
- BONUS:POSTRANGEADD|* to alter the range
- BONUS:RANGEADD|* to alter the range
Replacement
Requires a codeControl.lst file in the game mode. Reminder that the codeControl.lst file takes one token per line.
The codeControl.lst token is:
EQRANGE:x
"x" in this case is the name of the new formula system variable LOCAL to EQUIPMENT that contains the RANGE value. It is expected to be a NUMBER
NOTE: This is currently attached to the EQUIPMENT. Ideally, in the future, range will be attached to the EQUIPMENT.PART, but this is necessary for current backward compatibility in places where the Range is used and which are not aware of which PART they are operating upon. Expect a future code control to allow modification of this value to a PART once ToHit and Damage are complete.
Effects
If the EQRANGE code control is used, then any RANGE token in Equipment LST files will be reported as a "not supported" token. The EQRANGE control is either ON (new variable) or OFF (*RANGE LST tokens supported).
Any BONUS shown above will also be reported as an unsupported token if the EQRANGE code control is used.
The RANGE portions of the export system (output system) will continue to function. This includes portions of the following Export tokens: EQ, EQCONTAINERS, EQCONTAINER, EQCONTAINERW, WEAPON. The Range values are controlled by whether the EQRANGE code control is enabled. If not, it uses the RANGE as generated by the tokens. if it is, it uses the new formula provided as the argument to the EQRANGE code control.
In the long term, the preferred method will be to convert fetching the Range to getting the variable, but this is not currently possible due to lack of ability to do all the export of equipment in the new freemarker system.
Specific Considerations
Check for usage of "RANGE" in a formula in any Equipment. If this is used, then the game mode may not be convertable (yet) and/or a temporary variable may need to be created to carry that value in the old calculation system.
PC & Equipment REACH
Past Process
- REACH: in Equipment LST files
- REACHMULT in Equipment LST files
- REACH: in Race and Template LST files
- REACH term (JEP)
- REACHMULT term (JEP)
- RACEREACH term (JEP)
- PREREACH:
- BONUS:COMBAT|REACH
Replacement
Requires a codeControl.lst file in the game mode. Reminder that the codeControl.lst file takes one token per line.
The codeControl.lst tokens are:
- EQREACH:x
- PCREACH:x
- "x" in this case is the name of the new formula system variable that contains tha MAXDEX value for the PC or Equipment. It is expected to be a NUMBER
Do NOT only enable one of the two code controls above - use both or neither.
Effects
If the EQREACH and PCREACH code control is used, then any REACH or REACHMULT token above will be reported as a "not supported" token.
PREREACH: and any BONUS shown above will also be reported as an unsupported token if the EQREACH code control is used.
The REACH portions of the export system (output system) will continue to function. This includes the REACH export token. The values are controlled by whether the PCREACH and EQREACH code controls are enabled. If not, it uses the REACH as generated by the tokens. if it is, it uses the new formula provided as the argument to the EQREACH or PCREACH code controls.
Specific Considerations
None
PC & Equipment SPELLFAILURE
Past Process
- SPELLFAILURE: in Equipment LST files
- BONUS:MISC|SPELLFAILURE
- BONUS:EQMARMOR|SPELLFAILURE
- MODEQUIPSPELLFAILURE (term)
- EQSPELLFAIL (term)
Replacement
Requires a codeControl.lst file in the game mode. Reminder that the codeControl.lst file takes one token per line.
The codeControl.lst tokens are:
- EQSPELLFAILURE:x
- PCSPELLFAILURE:x
- "x" in this case is the name of the new formula system variable that contains tha MAXDEX value for the PC or Equipment. It is expected to be a NUMBER
Do NOT only enable one of the two code controls above - use both or neither.
Effects
If the EQSPELLFAILURE and PCSPELLFAILURE code control are used, then any SPELLFAILURE token on equipment will be reported as a "not supported" token.
Any BONUS:MISC|SPELLFAILURE or BONUS:EQMARMOR|SPELLFAILURE will also be reported as "not supported"
The SPELLFAILURE portions of the export system (output system) will continue to function. This includes portions of the following Export tokens: ARMOR, EQ, EQCONTAINERS, EQCONTAINER, EQCONTAINERW, SPELLFAILURE. The Spell Failure values are controlled by whether a SPELLFAILURE code control is enabled. If not, it uses the SPELLFAILURE as generated by the tokens. if it is, it uses the new formula provided as the argument to the SPELLFAILURE code controls.
Specific Considerations
Check for EQSPELLFAIL as a term in JEP formulas Check for MODEQUIPSPELLFAILURE in JEP formulas