Equipment Variables

From PCGen Wiki
Revision as of 05:40, 11 December 2010 by Barak (talk | contribs) (Added list of associated trackers for implementation of spec.)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

This feature would enable the ability of defining variables whose values would be associated with individual equipment items rather than the character it belongs to. This is needed for particularly complex equipment such as Mechas, Vehicles, Traps, Intelligent magic items, pretty much anything which brings a host of stats along with it. All equipment has stats and most of the commonly used stats have LST tags to handle them, stuff like DAMAGE, COST, WT to name a few. Complex equipment can have a number of new stats which we don't have LST tags for and it would be difficult for the code team to keep up with them. Being able to set a variable to a specific item gives us a mechanism to create any number of stats in the data which would be supported by one feature in the code.


Related Trackers

1041467 - MSRD Vehicle tags
987661 - Localalized Variables
857044 - Intelligent items

JIRA Trackers for spec implementation (entered 12/10/10)

NEWTAG-231 DEFINE:EQVAR
NEWTAG-232 BONUS:EQVAR
NEWTAG-233 PREEQVAR
NEWTAG-234 EQVAR for PREITEM
NEWTAG-235 EQVAR for PREEQUIP
NEWTAG-236 EQVAR for EQ output token
NEWTAG-236 HASEQVAR for EQ output token

LST Tags

Tag Name: DEFINE:EQVAR|x|y

Variables Used (x): Text (Equipment variable name)
Variables Used (y): Number (Initial value)

What it does:

  • Defines a variable who's value is specific to the Equipment it is defined in.
  • If more than one DEFINE tag for the same EQVAR is encountered the highest value is used.
  • Usage: once defined you can use EQVARs anywhere you can use a number, formula or normal VAR within equipment and EQMODs but not outside of them. This is because an EQVAR has it value in context of the equipment so using an EQVAR in a bonus formula within a feat is meaningless because it does not know from which equipment you want this value to be derived from and you may have several items with the same EQVAR but with different values.

Where it is used:

  • Valid in Equipment and EQMOD files only

Example:

DEFINE:EQVAR|MaxSpeed|0
Defines an Equipment variable named MaxSpeed and sets the initial value to 0.

Tag Name: BONUS:EQVAR|x,x|y,y|z

Variables Used (x): Text (Equipment variable name)
Variables Used (y): GLOBAL (Optional, applies to all equipment)
Variables Used (y): TYPE.Text (Optional, applies only if the equipment has this TYPE)
Variables Used (y): EQMODTYPE.Text (Optional, applies only if the equipment has an EQMOD with this TYPE)
Variables Used (y): Text (Optional, Equipment item name, applies to a specific item)

What it does:

  • BONUSes an EQVAR.
  • The Y property is meant to address the problem of how to bonus EQVARs across objects. Since you can have multiple items with the same EQVAR but with different values.
  • A BONUS:EQVAR in Equipment or EQMODs without any Y options will only effect EQVARs within the equipment item.
  • A BONUS:EQVAR outside of Equipment or EQMODs without any Y options will not effect anything. BONUS:EQVAR tags outside equipment must use one of the Y options to target equipment for bonusing. A BONUS:EQVAR outside of Equipment or EQMODs without any Y options should throw a message in the Debug Console.
  • A BONUS:EQVAR in Equipment or EQMODs with any Y options will effect all EQVARs contained in equipment targeted by the Y options including the item the bonus is in if it qualifies.
  • This bonus can be appended with standard PRExxx tags as well as bonus TYPE tags like most PRExxx tags.

Example:

BONUS:EQVAR|x,x|y,y|z
BONUSes an EQVAR

Tag Name: PREEQVARx:y,z

Variables Used (x): EQ (Equals).
Variables Used (x): GT (Greater Than).
Variables Used (x): GTEQ (Greater Than or Equal to).
Variables Used (x): LT (Less Than).
Variables Used (x): LTEQ (Less Than or Equal to).
Variables Used (x): NEQ (Not Equal to).
Variables Used (y): Text (The name of a variable - as used in a DEFINE: or BONUS:VAR statement).
Variables Used (z): Number (The value the variable is to be compared to).

What it does:

  • Tests the value of EQVARs.
  • When used as a stand alone tag in an EQMOD it is used to qualify an equipment item for the EQMOD. The equipment item must possess the EQVAR at the specified value to qualify for the EQMOD.
  • Can be used to qualify BONUSes and SPROPs in equipment and EQMOD files, when used this way it tests the value of the EQVAR in the equipment item and any attached EQMODs but does not look outside of itself (at other equipment the character possesses).
  • 0 is a valid value to test for, in the case of 0 PREEQVAR is testing to see if the EQVAR has been defined in the equipment item. If an item does not have a DEFINE or an EQMOD with a DEFINE for a specific EQVAR all PREEQVAR tests for it will fail.

Where it is used:

  • As a stand alone tag it is valid only in EQMOD files.
  • As a qualifier it is valid in equipment and EQMOD files.

Example:

PREEQVAREQ:Speed,55
Speed must equal 55
PREEQVARNEQ:Speed,55
Speed must NOT equal 55
PREEQVARGTEQ:Speed,55
Speed must be equal or greater than 55
PREEQVARLTEQ:Speed,55
Speed must be equal or less than 55


Testing for EQVARs outside of equipment

The need here is to test to see if the character has an item with a particular EQVAR. You might have an ability or bonus which is granted when in possession of a specific item, Like a Charisma bonus if you own a car with a top speed of 120+ or an enhancement to your Wisdom skills if you have an intelligent weapon with a high Charisma. I propose an enhancement to the PREITEM and PREEQUIP tags:

Examples:

PREITEM:1,EQVAR=Speed=>120
Must have one item with the Speed EQVAR with a value of greater than or equal to 120.
PREEQUIP:1,EQVAR=WeaponIntelligence>16
Must have an item with the WeaponIntelligence EQVAR with a value of greater than 16.


Output Tokens

Token Name: EQ.x.EQVAR.y

Variables Used (x): Number (The equipment position number - 0-based index).
Variables Used (y): Text (Equipment variable name)

What it does:

  • Outputs the specified EQVAR for the specified equipment.

Example:

EQ.0.EQVAR.MaxSpeed
Outputs the value of MaxSpeed for the first equipment item.

Token Name: EQ.x.HASEQVAR.y

Variables Used (x): Number (The equipment position number - 0-based index).
Variables Used (y): Text (Equipment variable name)

What it does:

  • Outputs Y (Yes) or N (No) as appropriate.
  • Makes this possible:
IFF(EQ.0.HASEQVAR.MaxSpeed:Y)
  • The value of the EQVAR can be 0 and still return Y, the EQVAR just need to be DEFINEd to pass.

Example:

EQ.0.HASEQVAR.MaxSpeed
Outputs Y (Yes) if the item has the EQVAR or N (No) if not.

Examples of usage

Here is how we might use EQVARs to code various source features (only relevant tags shown):

Equipment Item:

Shoe
EQMOD:GADGETSLOTS|2

Equipment Modifiers:

Gadget Slots
KEY:GADGET_SLOTS
DEFINE:EQVAR|AvailableGadgetSlots|0
CHOOSE:Gadget Slots|MIN=1|MAX=10
BONUS:EQVAR|AvailableGadgetSlots|%CHOICE
Hidden Telephone
KEY:HIDDEN_PHONE
PREEQVAR:1,AvailableGadgetSlots>0
BONUS:EQVAR|AvailableGadgetSlots|-1

In this example the EQVAR AvailableGadgetSlots is used to control the number of gadget EQMODs which can be added to an item (something which is very difficult to do now).

Equipment Modifiers:

Vehicle Stats
KEY:VEHICLE_STATS
DEFINE:EQVAR|VehicleSpeed|0
DEFINE:EQVAR|VehicleManuver|0
DEFINE:EQVAR|VehicleCargo|0

Equipment Item:

VW bug
EQMOD:VEHICLE_STATS
BONUS:EQVAR|VehicleSpeed|60
BONUS:EQVAR|VehicleManuver|4
BONUS:EQVAR|VehicleCargo|120

In this example a number of EQVARs are used to track specific vehicle stats for which PCGen does not already have a specialized tag for. A single EQMOD would have all the EQVARs needed for a broad equipment type (such as vehicles). A special block can then be created on the outputsheet for that equipment type.


Equipment Modifiers:


Intelligent Magic Item
KEY:INT_ITEM


Magic Item INT
PRETYPE:1,EQMOD=INT_ITEM
KEY:ITEM_INT
DEFINE:EQVAR|MagicItemINT|0
CHOOSE:Intelligence|MIN=3|MAX=18
BONUS:EQVAR|MagicItemINT|%CHOICE


Magic Item WIS
PRETYPE:1,EQMOD=INT_ITEM
KEY:ITEM_WIS
DEFINE:EQVAR|MagicItemWIS|0
CHOOSE:Wisdom|MIN=3|MAX=18
BONUS:EQVAR|MagicItemWIS|%CHOICE


Magic Item CHA
PRETYPE:1,EQMOD=INT_ITEM
KEY:ITEM_CHA
DEFINE:EQVAR|MagicItemCHA|0
CHOOSE:Charisma|MIN=3|MAX=18
BONUS:EQVAR|MagicItemCHA|%CHOICE


Equipment Item:


MoSaT's Magic Slingshot
EQMOD:INT_ITEM.ITEM_INT|10.ITEM_WIS|16.ITEM_CHA|12

In this example three EQVARs are used for an intelligent items mental attributes. It is coded in such a way as to allow such a weapon to be created in the customizer or coded in a dataset like the example slingshot.