CDOM Primitive Choice Set Concept Document

CDOM Primitive Choice Sets were added to PCGen in revision 5.16

Overview

CDOM Primitive Choice Sets are dynamic groups of Objects. Unlike CDOM References, Primitive Choice Sets mainly have contents that vary based on the PlayerCharacter. In addition, Primitive Choice Sets are not restricted to CDOM Objects, and may contains other classes of objects.

During the load of PCC/LST files, Primitive Choice Sets are created and loaded with the necessary information required to identify their underlying contents. The only additional information required to establish the contents of the Primitive Choice Set is the PlayerCharacter. With a few exceptions, Primitive Choice Sets are dynamic, meaning they may change their contents based on the PlayerCharacter used to retrieve the underlying collection of objects.

As the name implies, Primitive Choice Sets are generally used in places where a choice needs to be made during construction of a PlayerCharacter. This includes many of the ADD tokens.

Primitive Choice Sets can be found in the pcgen.cdom.choiceset package.

Types of Primitive Choice Sets

Basic Sets

Basic Primitive Choice Sets have a single underlying constraint or fixed set of objects used to identify the collection of objects in the Primitive Choice Set for a given PlayerCharacter.

Compound Sets

When more than one Primitive Choice Set is required to identify the Objects that may be used, a Compound Primitive Choice Set can be created. Generally, there are two Compound Primitive Choice Sets: CompoundOrChoiceSet and CompoundAndChoiceSet. As the names imply, these provide a union (CompoundOr) or Intersection (CompoundAnd) of the underlying Primitive Choice Sets.

Decorators

Primitive Choice Set is an interface, so Decorators are also available to alter the contents of a PrimitiveChoiceSet. The easiest Decorator to understand is a QualifiedDecorator, which restricts the returned CDOM Objects to those objects that the PlayerCharacter used to retrieve the underlying collection of CDOM Objects is qualified to possess.

Lifecycle of a Primitive Choice Set

1. Primitive Choice Set Creation: When LST files are loaded, and groups of objects that will be dependent upon the contents of the PlayerCharacter are referred to in the data, a CDOM Primitive Choice Set is created. Primitive Choice Sets are constructed by the individual token in the Token/Loader system; no centralized construction takes place.
2. Resolution: When a PlayerCharacter is being processed, the various Primitive Choice Sets may be queried to determine the the objects underlying the Primitive Choice Set given the current PlayerCharacter.
3. Write: Primitive Choice Sets may be written back to an LST file, and each Primitive Choice Set has a getLSTformat(boolean) method that provides the unique method of identifying the reference that can be stored in a persistent state (in an LST file).

Characteristics/Weaknesses of Primitive Choice Sets

This section refers to PCGen 5.16

1. Currently, the LST syntax in PCGen is inconsistent about the use of "ANY" and "ALL", both of which are used to refer to the set of all objects of a given class. This causes some problems for Primitive Choice Sets, as the tokens that leverage the Primitive Choice Set system include those inconsistent tokens. Therefore, the getLSTformat method for the PrimitiveChoiceSet interface includes a boolean operator that controls whether a CDOM Reference referring to the set of all objects is output as "ANY" or "ALL" for the Primitive Choice Set.
2. While certain tokens are heavily dependent on Primitive Choice Sets, the Primitive Choice Sets themselves must be stored in the core. This is actually a function of the existing token plugin system that makes it challenging to construct objects that are not present in the core or share classes across tokens/plugins.