CDOM Choice Actors Concept Document

Overview

CDOM Choice Actors are objects responsible for carrying out the actions of a choice made during construction of a PlayerCharacter. A Choice Actor may also have the ability to limit the choices available to a PlayerCharacter.

Choice Actors are generally used in conjunction with Primitive Choice Sets to implement a choice made during construction of a PlayerCharacter.

The Tokens requiring action be taken from a choice generally serve as their own CDOM Choice Actors. Thus, Choice Actors can generally be found in the plugin.lsttokens package.

Types of Choice Actors

Choice Actors

A basic Choice Actor can constrain the choices available to a Player Character and take action when a Player Character selects a specific choice that the Choice Actor was representing.

Persistent Choice Actors

A Persistent Choice Actor is a specialized form of a Choice Actor that has additional capabilities allowing the choice made to be stored into and restored from a persistent format (generally stored in the PCG file, PCGen's Player Character storage format).

Responsibilities of a Choice Actor

1. Limit the choices available to a Player Character: The allow(T, PlayerCharacter, boolean) method of Choice Actor is used to constrain the choices available to a Player Character. The available choices may be limited due to a choice not being available a second time (e.g. applying a Template a second time), or the Player Character may not be qualified for the choice (due to Prerequisites on the object)
2. Take action once a choice is made: Once a selection is made during construction of a Player Character, the applyChoice(CDOMObject, T, PlayerCharacter) method is used to apply the choice to a Player Character. This method is responsible for all actions related to applying the choice, including any necessary associations or methods to store a choice so it may later be removed from a Player Character.

Additional Responsibilities of a Persistent Choice Actor

In addition to the basic responsibilities of a Choice Actor, a Persistent Choice Actor has additional function:

1. In order to be able to store a choice into a format which can be accurately retrieved from a persistent state, a Persistent Choice Actor has encodeChoice and decodeChoice methods. Note that the encoding may not sufficiently encode to be stored into a file or format which restricts certain characters (such as URLs), it simply encodes into an identifying String. There is also no guarantee that this encoding is human readable, simply that the encoding is uniquely identifying such that the decodeChoice method of the Persistent Choice Actor is capable of decoding the String into the choice object.
2. In order to be able to restore the function of a choice to a Player Character when the Player Character has been reopened from a persistent state, a Persistent Choice Actor has a restoreChoice method. Note that this differs from the apply method inherited from the Choice Actor, as this method is only responsible for items that were not otherwise stored in a persistent state. In many cases in PCGen 5.16, a Persistent Choice Actor may have no action to take in the restoreChoice method, as such action would be redundant and produce errors.
3. A Persistent Choice Actor also is capable of removing a choice from a Player Character. This is necessary so that the appropriate consequences of removal can be applied to a Player Character. This would typically occur due to the loss of an object that granted a choice (that choice having been applied by the Persistent Choice Actor).

Characteristics/Weaknesses of Choice Actors

This section refers to PCGen 5.16

1. While not properly a weakness of Choice Actors, the existing code structure does not historically reflect every choice made during construction of a PlayerCharacter. It may be a noble long term goal to make all Choice Actors into Persistent Choice Actors.
2. Another weakness of the existing core of PCGen reflects back on how Choice Actors are implemented. Many Persistent Choice Actors have an empty restoreChoice method, when it would seem that restoreChoice would be very similar to the apply method. Either convergence of these two methods or elimination of restoreChoice is certainly a long-term goal, but is dependent upon a redesign of the Player Character data model to ensure all required information is written out and restored in a repeatable fashion.