Formula Parser Conversion Instructions

Code Changes

Preparation

• Define the name of the feature to be converted. Add the name of the feature to pcgen.cdom.enumeration.FeatureKey ... For purposes of the rest of this description, it is called "FKEY"
• Define the namespace and name of the new variable. For purposes of the rest of this description, we will use numbers (VAR namespace) and "NEWVAR" as the variable name

Tokens

• Determine if it is a full token or a partial output token that is being deprecated
  • In the case of a full token, Take the existing output token(s) and deprecate the output token. Note: It is NOT necessary in this case to support ANY output if the feature is set to FORMULA.
  • In the case of a partial token, then a transition is required (mainly to be able to increment across the same items consistently), and the Feature being set to FORMULA needs to trigger the old output token to draw from the new system

Bracket the "old style output" as such:

if (SettingsHandler.getGame().getFeature(FeatureKey.FKEY).equals(FeatureState.FORMULA))
{
  //This assumes just simple formatting, if something more complex is needed
  //take the returned object and cast / format as necessary
  return pc.getGlobal("VAR", "NEWVAR").toString();
}
else
{
  //old behavior
}

• Determine if any BONUS tokens are involved. If so, determine if it is a full or partial BONUS token For purposes of the rest of this description, we assume it is BONUSTYPE BONUSNAME, e.g.:

BONUS:BONUSTYPE|BONUSNAME|...

• If full:
  • Take the existing BONUS token and deprecate it
  • Add an error message to the token parse when the feature is on (there are various ways to do this depending on the type of BONUS token being altered).

• If partial, you will need to gate some capability based on the feature setting. For a MultiTagBonusObject this might look like:

@Override
protected void addBonusInfo(Object obj)
{
  FeatureState featurestate = SettingsHandler.getGame().getFeature(FeatureKey.FKEY);
  if (featurestate.equals(FeatureState.FORMULA) && Integer.valueOf(3).equals(obj))
  {
    Logging.errorPrint("BONUS BONUSTYPE|BONUSNAME is not supported when Feature FKEY=FORMULA");
  }
  super.addBonusInfo(obj);
}

Note in this example that the bonusname being removed is in the 4th position (index 3) of the array used in the MultiTagBonusObject.

Enable

• Define the feature in the loader. This is done in pcgen.persistence.SourceFileLoader ... There are two convenience methods provided, so the only changes need to occur in the defineBuiltinVariables method. Ensure there is an appropriate defineNamespace call for the format and name of the namespace being used, e.g.:

defineNamespace(varContext, Number.class, "VAR");

The insert a line to define the variable:

defineVariable(varContext, "VAR", "NewVar");

This enables the use of MODIFY and MODIFYOTHER to modify that variable.