mirror of
https://github.com/Oreolek/raconteur.git
synced 2024-04-25 21:49:22 +03:00
Document qualities.js
This commit is contained in:
parent
5e9ef97b13
commit
93cbe88060
|
@ -179,12 +179,13 @@ situation('progress-bar', {
|
|||
qualities.create() to get a factory.
|
||||
*/
|
||||
|
||||
var DifficultyQuality = function (title, spec) {
|
||||
undum.QualityDefinition.call(this, title, spec);
|
||||
var DifficultyQuality = function (title, threshold) {
|
||||
undum.QualityDefinition.call(this, title);
|
||||
this.threshold = threshold;
|
||||
};
|
||||
|
||||
DifficultyQuality.prototype.format = function (character, value) {
|
||||
if (value > 5) return "hard";
|
||||
if (value > this.threshold) return "hard";
|
||||
return "easy";
|
||||
};
|
||||
|
||||
|
@ -199,8 +200,8 @@ qualities({
|
|||
},
|
||||
settings: {
|
||||
name: 'Settings',
|
||||
combatDifficulty: difficulty("Combat"),
|
||||
puzzleDifficulty: qualities.use(DifficultyQuality, "Puzzles")
|
||||
combatDifficulty: difficulty("Combat", 5),
|
||||
puzzleDifficulty: qualities.use(DifficultyQuality, "Puzzles", 3)
|
||||
}
|
||||
});
|
||||
|
||||
|
|
102
docs/qualities.md
Normal file
102
docs/qualities.md
Normal file
|
@ -0,0 +1,102 @@
|
|||
# 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:
|
||||
|
||||
```javascript
|
||||
{
|
||||
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
|
||||
|
||||
```javascript
|
||||
/* 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()*/
|
||||
```
|
||||
```coffeescript
|
||||
# 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)
|
||||
```
|
|
@ -6,3 +6,4 @@ pages:
|
|||
- ['situation.md', 'API Documentation', 'situation.js']
|
||||
- ['elements.md', 'API Documentation', 'elements.js']
|
||||
- ['oneOf.md', 'API Documentation', 'oneOf.js']
|
||||
- ['qualities.md', 'API Documentation', 'qualities.js']
|
||||
|
|
Loading…
Reference in a new issue