Difference between revisions of "Formula Parser Equip Vars Demo"

From PCGen Wiki
Jump to: navigation, search
m
 
(2 intermediate revisions by the same user not shown)
Line 3: Line 3:
 
   |}
 
   |}
  
=Description=
+
=WARNING: THIS IS DEPRECATED=
 +
=Deprecated=
  
This page describes how to use the Formula Parser Equipment Variables Demo, provided in a sandbox (in Subversion)
+
The remainders here are saved for archival purposes at the moment (they are a few useful tidbits the code folks don't want to retype from scratch)
  
=Location=
+
Please see [[Setting up the new Formula System]]
 
 
The Demo is in sandbox/EqVarDemo/PCGen and can be checked out from subversion as any other branch of PCGen.  Please use build.xml (and ant) to build PCGen, as Gradle support may not be fully enabled in this branch.
 
  
 
=General Comments and Limitations=
 
=General Comments and Limitations=
Line 18: Line 17:
 
* Is not intended to cover unreasonably high numbers
 
* Is not intended to cover unreasonably high numbers
 
* There is at least one UI problem, in that the UI doesn't realize that the PRExxx status of an EqMod can dynamically changes when another EqMod is added.  The EqMod in question has to be selected to turn red.
 
* There is at least one UI problem, in that the UI doesn't realize that the PRExxx status of an EqMod can dynamically changes when another EqMod is added.  The EqMod in question has to be selected to turn red.
 
=New Campaign File Tokens=
 
 
==DATACONTROL==
 
 
DATACONTROL: is a new Campaign file token (for PCC files).  It is treated "recursively" like other tokens, e.g. TEMPLATE. 
 
 
Limitations: It does not support PRExxx or INCLUDE/EXCLUDE.
 
 
Future Development: It is possible that PRExxx could be supported, it is unlikely that INCLUDE/EXCLUDE would be supported due to the nature of definitions not being traditional objects (too much unique code)
 
 
==GLOBALMODIFIER==
 
 
GLOBALMODIFIER: is a new Campaign file token (for PCC files).  It is treated "recursively" like other tokens, e.g. TEMPLATE. 
 
 
Limitations: It does not support PRExxx or INCLUDE/EXCLUDE.
 
 
Future Development: It is possible that PRExxx could be supported, it is unlikely that INCLUDE/EXCLUDE would be supported due to the nature of variables not being traditional objects (too much unique code)
 
 
==VARIABLE==
 
 
VARIABLE: is a new Campaign file token (for PCC files).  It is treated "recursively" like other tokens, e.g. TEMPLATE. 
 
 
Limitations: It does not support PRExxx or INCLUDE/EXCLUDE.
 
 
Future Development: It is possible that PRExxx could be supported, it is unlikely that INCLUDE/EXCLUDE would be supported due to the nature of variables not being traditional objects (too much unique code)
 
 
=New Data Control File Tokens=
 
 
==NAMESPACEDEF==
 
 
NAMESPACEDEF: is a token for the Data Control File defined by the DATACONTROL: PCC token
 
 
NAMESPACEDEF:x|y
 
 
x is a legal data format (currently NUMBER, STRING, ORDEREDPAIR)
 
y is a name for the data type ("traditional variables" should be defined as "VAR", other items are up to the data team)
 
 
Known Limitations:
 
* x will have a lot more legal values going forward (STRING, etc. - many of those that are legal on QUALIFY today)
 
 
Note that a y value MUST have a NAMESPACEDEF in the Data Control file for it to be legal in the "y" slot of LOCAL in the Variable File.
 
 
==DEFAULTVARIABLEVALUE==
 
 
The following tokens are REQUIRED in the game mode to set the default value of a variable type:
 
DEFAULTVARIABLEVALUE:NUMBER|0
 
DEFAULTVARIABLEVALUE:ORDEREDPAIR|0,0
 
 
The Syntax is:
 
 
DEFAULTVARIABLEVALUE:x|y
 
 
x is a data format (defined elsewhere). Some valid data formats are NUMBER, STRING, POINT
 
y is a valid string representation of the data format in x. So for NUMBER it would be a valid number, such as zero. For Point, it has to be a valid Point, such as 0,0
 
  
 
=New Global Modifier Tokens=
 
=New Global Modifier Tokens=
Line 79: Line 23:
  
 
Tokens must appear one per line in the Global Modifier file
 
Tokens must appear one per line in the Global Modifier file
 
=New Variable File Tokens=
 
 
==LOCAL==
 
 
LOCAL: is a token for the Variable files defined by the VARIABLE: PCC token. 
 
 
LOCAL:x|y=z
 
 
x is a legal variable scope
 
y is a variable type (see NAMESPACEDEF)
 
z is the variable name
 
 
NOTE: y is OPTIONAL and if not present "VAR" is the assumed value
 
 
These have 2 arguments, the scope, and the variable name. For example:
 
LOCAL:EQUIPMENT|ModCount
 
 
Limitations:
 
* EQUIPMENT and EQUIPMENT.PART are the legal variable scopes that are supported (more below in discussion of Scope of Variables)
 
* By Design: Must appear as the first token on a line
 
 
Future Development:
 
* Resolve whether "EQUIPMENT" is actually the item on the line or whether it is "Equipment Variables" (how the code thinks internally).  This is eventually a risk of tying closely the code and the data, so this requires consideration of how object types are defined (a much longer discussion than belongs here - please ask on _dev if you are interested)
 
 
==EXPLANATION==
 
 
EXPLANATION: is a free-text token (no parsing is really done) that is designed to describe why a variable exists
 
 
Limitations:
 
* By Design: Must not appear as the first token on a line
 
 
Behavior:
 
* Overwrites (as if someone would use it twice??)
 
 
==Future Development==
 
 
At least "GLOBAL" would be a future development item (though it would "default" to that, so the following variable file is valid:
 
MyGlobalVariable
 
GLOBAL:MyOtherGlobalVariable
 
LOCAL:EQUIPMENT|MyLocalVar
 
 
=New Campaign File REQUIREMENTS=
 
 
There are two types of files: Data Control and Variable
 
 
==Data Control==
 
 
Identifies variable types
 
 
The following tokens are REQUIRED in data control file:
 
NAMESPACEDEF:NUMBER|VAR
 
NAMESPACEDEF:ORDEREDPAIR|AREA
 
 
==Variable File==
 
 
Identifies variables that can be used in the data
 
 
Note that the GLOBAL and LOCAL tokens today IMPLY VAR. Meaning
 
GLOBAL:MyOtherGlobalVariable
 
is (to the code) actually
 
GLOBAL:VAR|MyOtherGlobalVariable
 
 
Note this can be combined with the implied GLOBAL, so
 
MyGlobalVariable
 
is (to the code) actually
 
GLOBAL:VAR|MyGlobalVariable
 
 
We will need to decide if all these items can stay implied, but I believe they can.
 
 
=Prerequisites=
 
 
==PREEQVAR==
 
 
PREEQVARxxx exist as PRE tokens.  All valid suffixes (LT, EQ, NEQ, etc.) are supported.  Please see the PREVAR documentation if you are not familiar with the legal suffixes.
 
 
Syntax:
 
PREEQVARxx:y,z
 
 
Limitations:
 
* Only Numbers (Integer or Decimal) or a single, legal variable name are supported as y and z.
 
 
This refers to variables that are "EQUIPMENT" in the LOCAL: line of the Variable file
 
 
==PREEQPARTVAR==
 
 
PREEQPARTVARxxx exist as PRE tokens.  All valid suffixes (LT, EQ, NEQ, etc.) are supported.  Please see the PREVAR documentation if you are not familiar with the legal suffixes.
 
 
Syntax:
 
PREEQPARTVARxx:y,z
 
 
Limitations:
 
* Only Numbers (Integer or Decimal) or a single, legal variable name are supported as y and z.
 
 
This refers to variables that are "EQUIPMENT.PART" in the LOCAL: line of the Variable file
 
 
 
=Modify Token=
 
 
==Syntax==
 
 
MODIFY:w|x|y|PRIORITY=z
 
 
w is the variable name as defined in the Variable LST file
 
x is the modification type.  Legal types are shown below.
 
y is the modification (based on the type, see below)
 
z is an OPTIONAL priority.  If not specified, it is assumed to be zero.
 
 
==Priority==
 
 
Items are processed in a Natural Priority order.  PRIORITY is used to order any modifiers, then a natural ordering is used.  So:
 
MODIFY:Var|ADD|4
 
MODIFY:Var|MULTIPLY|5
 
 
are applied, the Multiplication will ALWAYS occur first, regardless of token order in the file. If you are unsure of natural order, use PRIORITY to control processing order.
 
 
Priority must be >= 0
 
 
Items are processed from the lowest priority to the highest (highest is applied last, so a SET with a high priority is applied last)
 
 
A clarification on natural ordering: it does NOT replace priority if not defined.  The two priority comparisons (user priority and natural priority) are independent.  So an item of user priority 1 and natural priority 3 will be processed before user priority 2 and natural priority 2, solely based on the user priority)
 
 
==Legal Types==
 
 
===ADD===
 
 
ADD takes a Numeric Argument. 
 
 
Equations using other variables are allowed, but direct values will be faster. 
 
 
The 'natural' priority is 3.
 
 
===MULTIPLY===
 
 
MULTIPLY takes a Numeric Argument. 
 
 
Equations using other variables are allowed, but direct values will be faster. 
 
 
The 'natural' priority is 2.
 
 
===MAX===
 
 
MAX takes a Numeric Argument. 
 
 
Equations using other variables are allowed, but direct values will be faster. 
 
 
This sets an upper bound on the value (a maximum that the value can be)
 
 
The 'natural' priority is 4.
 
 
===MIN===
 
 
MIN takes a Numeric Argument. 
 
 
Equations using other variables are allowed, but direct values will be faster. 
 
 
This sets a lower bound on the value (a minimum that the value can be)
 
 
The 'natural' priority is 5.
 
 
===SET===
 
 
SET takes a Numeric Argument. 
 
 
Equations using other variables are allowed, but direct values will be faster. 
 
 
This sets the value (any previous value is overwritten/ignored)
 
 
The 'natural' priority is 0.
 
 
If you have a value that was previously modified from the default (or you want to enable that based on using a higher PRIORITY= then you should use the value() function to capture the existing value.  Thus the following are equivalent:
 
MODIFY:Foo|ADD|4
 
MODIFY:Foo|SOLVE|value()+4
 
 
Note that the ADD is preferred because it is smaller in memory and faster to process, but more complex calculations will obviously require SOLVE
 
 
=ModifyOther Token=
 
 
==Syntax==
 
 
MODIFYOTHER:u|v|w|x|y|PRIORITY=z
 
 
u is the scope of modification (this must be a legal variable scope)
 
v is the grouping to be modified
 
w is the variable name as defined in the Variable LST file
 
x is the modification type.  Legal types are shown in the docs for MODIFY
 
y is the modification (based on the type, see MODIFY)
 
z is an OPTIONAL priority.  If not specified, it is assumed to be zero.
 
 
A note on u: A Legal Variable Scope implies it must be an item that is also legal as the "x" value of the LOCAL: token from the Variable file
 
 
Limitations:
 
* Currently the only supported Groupings are "ALL" or "GROUP=x" where x is a value provided by the (new) GROUP: global token.  It is expected for GROUP to be isolated to the EqVar Demo and not brought to Trunk.  For longer-term use in Trunk, it will likely be based on [[FACT Token]] and [[FACTSET Token]]
 
 
w, z, y, z are the same as MODIFY:, but have variables legal as if they were in the scope defined by u (Meaning you can put MODIFYOTHER: in an Ability and if "u" is EQUIPMENT, then you can modify local variables in Equipment)
 
 
See MODIFY above for how priority works.
 
 
==An Example==
 
 
A decent example of using MODIFYOTHER may be from AEG's Feats (3.5e).  Currently we are forced to do a special EqMod:
 
Assassin's Blade TYPE:Weapon PRETYPE:1,Melee BONUS:EQMWEAPON|CRITRANGEADD|1|PREFEAT:1,Assassin
 
 
With MODIFYOTHER, this EqMod is unnecessary:
 
Assassin CATEGORY:FEAT MODIFYOTHER:EQUIPMENT|GROUP=Melee|EqCritRange|ADD|1|PRIORITY=5000
 
 
This assumes we have something like:
 
Longsword GROUP:Melee PART:1|MODIFY:CritRange|SET|1
 
 
And in GlobalModifiers
 
MODIFYOTHER:EQUIPMENT.PART|ALL|CritRange|SOLVE|value()+EqCritRange
 
 
Note:
 
* The MODIFYOTHER in Assassin has to act on a variable in EQUIPMENT since the GROUP is actually part of the Equipment not the Equipment Part (this is not strictly required, but applying the groups to parts gets to be a pain).  Thus we use the SOLVE to add the Equipment-level CritRange Bonus to the head (where it is actually applicable in terms of how it would be output)
 
 
=Functions Supported=
 
 
The following functions are supported:
 
* min
 
* max
 
* ceil
 
* floor
 
* if
 
* abs
 
* round
 
 
If you have questions about the behavior, see the existing PCGen docs.
 
 
=About Variable Scope=
 
 
In this demo, there are now TWO local scopes:
 
* One for Equipment
 
* One for Equipment Parts
 
 
The distinction is where they are applied.  If it is necessary to have a variable controlling what EQMODs are legal, it is likely that is related to the Part (because EqMods are applied to Parts (aka Heads) not to Equipment.) ... So the charms stuff from FantasyCraft (for example) are likely to be on PARTs, not on Equipment.
 
 
 
 
 
 
 
 
 
=Walkthrough of the connections=
 
 
Note the Game Mode MISCINFO file defines a default for NUMBER and POINT
 
 
Only items with a default value in the Misc Info file may be used as the first argument on the TYPE line in the variable file.
 
 
Therefore:
 
NAMESPACEDEF:NUMBER|VAR
 
 
Defines an internal "variable type" of "VAR" that holds numbers.
 
 
This is done because we may want something like:
 
NAMESPACEDEF:NUMBER|MOVEMENT
 
 
This allows us to have multiple, non-conflicting types of numbers in the data.
 
 
Once the second argument is used in a TYPE entry, then it can be used in other data, including LOCAL and GLOBAL in the variable file and MODIFY in other LST files.  Items are referred to by the second argument, NOT the underlying type.  So the following would be reasonable data:
 
NAMESPACEDEF:ORDEREDPAIR|AREA
 
AREA|Face (note that since GLOBAL is implied, this is equal to GLOBAL:AREA|Face)
 
MODIFY:AREA=Face|SET|10,10
 
 
Note that we are asking the data team to put the TYPE into the var file, but we are currently implying the Face in the code.  This is so that we can "hide" the use of GLOBAL in the test (since that would cause a few confusing issues)
 
 
Note also that MODIFY CANNOT be used with the "=" in the first argument, so please don't try it!  I am echoing long term intent, not immediate syntax.
 

Latest revision as of 02:04, 25 January 2018

WARNING: THIS IS DEPRECATED

Deprecated

The remainders here are saved for archival purposes at the moment (they are a few useful tidbits the code folks don't want to retype from scratch)

Please see Setting up the new Formula System

General Comments and Limitations

When possible, use integers. The system is capable of doing integer arithmetic, so 1+2 will produce 3, whereas 1.0+2.0 may produce 2.9999999999999.

Known Limitations:

  • Is not intended to cover unreasonably high numbers
  • There is at least one UI problem, in that the UI doesn't realize that the PRExxx status of an EqMod can dynamically changes when another EqMod is added. The EqMod in question has to be selected to turn red.

New Global Modifier Tokens

MODIFY: and MODIFYOTHER: (see below for the global tokens) are legal in the Global Modifier file. No other tokens are legal.

Tokens must appear one per line in the Global Modifier file