New Tag - FACT

From PCGen Wiki
Jump to: navigation, search

New Tag - Fact

Introduced to allow Facts about the PC or object to be set. More information about this tag is here: http://wiki.pcgen.org/FACT_Token


Base Tag

  • FACT:x|y
  • x is an identifier
  • y is the factual value

Example: FACT:IsPC|true

  • Sets IsPC identifier to the Boolean Factual Value of 'true'
  • Notes: A FACT must be premade in the //DATACONTROL.LST// file. Unlike the older ASPECT tag, FACTs are required to exist beforehand so the system knows what type of fact it is using, and where.

PCC File

A Datacontrol file must exist in order to use FACTs.

DATACONTROL:x.lst

  • The same naming conventions are used, except as special high level files, we use a double underscore (__) between abbreviation and datacontrols.
  • Example: DATACONTROL:cr__datacontrols.lst


DATACONTROL FILE

This file requires very specific tags in order to function.


FACTDEF

The first tag must always be FACTDEF:x|y

  • x is a file type (e.g. DEITY for Deity LST files)
  • y is the identifier (then usable as x in the FACT LST token)

File Types for (x):

  • GLOBAL
  • ABILITY
  • ALIGNMENT
  • CHECK
  • CLASS
  • COMPANIONMOD
  • DEITY
  • DOMAIN
  • EQUIPMENT
  • KIT
  • LANGUAGE
  • RACE
  • SIZEADJUSTMENT
  • SKILL
  • SPELL
  • STAT
  • TEMPLATE
  • WEAPONPROF


The rest of the tags follow by at least one tab spacing as per normal.


DATAFORMAT

DATAFORMAT:x

This token is REQUIRED. A FACTDEF with no DATAFORMAT will produce an LST load error.

Note: The "x" Items will be hardcoded. In addition to "STRING", it is expected that the same items that are valid as the "x" value of QUALIFY (the existing Global token) would also be legal here.

Note: This is an exception to a duplicate FACTDEF: acting as a MOD. Specifically, A DATAFORMAT: with a type that does not match a previous value will produce an error, since you have two conflicting FACTs with the same identifier.

Legal Values for x:

ALIGNMENT
BOOLEAN
CLASS
GRIDPOINT
NUMBER
STAT
STRING

A reminder that certain items (Alignment, Stat) are referred to by their abbreviation not their name/key

VISIBLE

For any given FACTDEF, we can control how that FACT is used. This allows us to make it visible to the end user, or display in output.

VISIBLE:x

x is:

YES
NO (default is NO)
DISPLAY
EXPORT

For example:

FACTDEF:DEITY|Symbol <> DATAFORMAT:STRING <> VISIBLE:EXPORT

EXPORT or YES would enable the output in Freemarker:

${deity.symbol}

(which would produce an error if VISIBLE:NO or VISIBLE:DISPLAY)

EXPORT or YES or will trigger display in the UI, specifically in the items about the object, in Gui2InfoDisplay (code will know the meaning of this)

In case of .MOD (see FACTDEF for multiple definitions acting as a .MOD) this overwrites

SELECTABLE

For any given FACTDEF, we can control how that FACT is used. This allows us to make it usable in CHOOSE or other locations where a Primitive is legal:

SELECTABLE:

x is:

YES
NO (default is NO)

For example:

FACTDEF:DEITY|Align <> DATAFORMAT:ALIGNMENT <> VISIBLE:YES <> SELECTABLE:YES

SELECTABLE:YES enables use in a CHOOSE:

CHOOSE:DEITY|ALIGN=LG

Given the above FACTDEF, this would allow a choice of any Deity with the 'ALIGN' FACT set to 'LG' (this emulates the ALIGN= item we have in CHOOSE:DEITY today)

(It would produce an error if the FACTDEF for ALIGN was SELECTABLE:NO)

In case of .MOD (see FACTDEF for multiple definitions acting as a .MOD) this overwrites

REQUIRED

For any given FACTDEF, we can make that FACT required for a certain type of object.

REQUIRED:x

x is:

YES
NO (default is NO)

For example:

FACTDEF:DEITY|Align <> DATAFORMAT:ALIGNMENT <> VISIBLE:YES <> REQUIRED:YES

This would then trigger an LST load error if a Deity did not have the "ALIGN" Fact assigned.

In case of .MOD (see FACTDEF for multiple definitions acting as a .MOD) this overwrites

As caution to the data team: Use of this forces it across ALL loaded data, NOT JUST DATA FROM THE LOCAL PCC FILE. That likely means this is used sparingly, and only in base sets, otherwise the additional sets would have to .MOD a lot of stuff...

WARNING: A FACTDEF where the "x" value of the FACTDEF token is "GLOBAL" MUST NOT be Required. Using REQUIRED:YES on a global FACTDEF will cause a load error.

DISPLAYNAME

For any given FACTDEF, we can control the name displayed for that type of item in the UI

DISPLAYNAME:x

x is a String (used to describe this fact in the UI)

Intent is that this is used to describe the object and is the string that will be displayed in the UI

In case of .MOD (see FACTDEF for multiple definitions acting as a .MOD) this overwrites

EXPLANATION

For any given FACTDEF, we can explain the purpose it serves in the data

EXPLANATION:x

x is a String

Intent is this is used to describe what the object is for purposes of the LST editor or readers of the data

In case of .MOD (see FACTDEF for multiple definitions acting as a .MOD) this overwrites

Global PREFACT

Of course, being able to define a FACT also demands something like:

PREFACT:w,x,y=z
w is a number
x is the type (e.g. DEITY)
y is the identifier (e.g. SYMBOL)
z is the required value

For example:

PREFACT:1,DEITY,SYMBOL=Star

"x" matches the same strings used in the output file, which are shown on the FreeMarker Facet Output page. In some cases, an additional piece of information is required, for example:

PREFACT:1,EQUIPMENT.EQUIPPED,COLOR=Red