qualities.js

This module provides an interface for setting up quality definitions in Undum. Essentially it takes a single plain object, and builds definition and groups from that object, exposing an API where quality definitions are members of group objects.

Export

qualities(Object spec) -> null

Creates the QualityDefinition and QualityGroup objects defined by the spec, and registers them in Undum. This is designed to be called only once from the story source file.

The spec object follows this interface:

{
  quality_group: {
    name: "Quality Group",
    options: {},
    quality1: QualityFactory("Name"),
    quality2: QualityFactory("Name")
  }
}

Which is to say, it is a plain object; members of that plain object are quality groups. Each quality group object optionally supplies a name property and an options property. name is either a String (The title of the quality group, displayed as a heading in the game) or null (by default), indicating that no heading needs to be displayed. options is an options object for Undum's QualityGroup constructor; see Undum documentation.

Each other property of a group object is taken as a quality. identifiers for qualities should be unique across the whole game, not merely across groups, because this structure will be "flattened" later. To create a quality using this API, you use a factory rather than one of Undum's supplied constructors directly.

The following factories are provided as properties of qualities, and correspond to the following Undum constructors:

Factory	Constructor
integer	IntegerQuality
nonZeroInteger	NonZeroIntegerQuality
numeric	NumericQuality
fudgeAdjectives	FudgeAdjectivesQuality
onOff	OnOffQuality
yesNo	YesNoQuality
wordScale	WordScaleQuality

You can create your own factories by passing the constructor of a QualityDefinition implementation to qualities.create(). qualities.use() is a factory that takes a constructor as its first argument, and passes all other arguments on to that constructor, acting as a sort of shim.

Extended Example

# A QualityDefinition implementation constructor.
DifficultyQuality = (title, threshold) ->
  undum.QualityDefinition.call(this, title)
  this.threshold = threshold

DifficultyQuality.prototype.format = (character, value) ->
  if value > this.threshold then "hard" else "easy"

# Create a factory to use in our definition spec.
difficulty = qualities.create DifficultyQuality

# Give a specification of our quality definitions to the qualities()
# function.
qualities
  stats:
    name: 'Statistics'
    perception: qualities.integer("Perception")
    intelligence: qualities.integer("Intelligence")
    size: qualities.fudgeAdjectives("Size")
  settings:
    name: 'Settings'
    combatDifficulty: difficulty("Combat", 5) # Is equivalent to...
    puzzleDifficulty: qualities.use(DifficultyQuality, "Puzzles", 3)

/* A QualityDefinition implementation constructor. */
var DifficultyQuality = function (title, threshold) {
  undum.QualityDefinition.call(this, title);
  this.threshold = threshold;
};

DifficultyQuality.prototype.format = function (character, value) {
  if (value > this.threshold) return "hard";
  return "easy";
};

/* Create a factory to use in our definition spec. */
var difficulty = qualities.create(DifficultyQuality);

/* Give a specification of our quality definitions to the qualities()
   function. */
qualities({
  stats: {
    name: 'Statistics',
    perception: qualities.integer("Perception"),
    intelligence: qualities.integer("Intelligence"),
    size: qualities.fudgeAdjectives("Size")
  },
  settings: {
    name: 'Settings',
    combatDifficulty: difficulty("Combat", 5), // Is equivalent to...
    puzzleDifficulty: qualities.use(DifficultyQuality, "Puzzles", 3)
  }
});

/* Remember that qualities have to have their initial value set in
undum.game.init()*/