mirror of
https://github.com/Oreolek/undum-docs.git
synced 2024-06-26 03:40:52 +03:00
English version
This commit is contained in:
parent
cab0973a9e
commit
160189c7cd
122
en/HTML.md
122
en/HTML.md
|
@ -1,7 +1,5 @@
|
|||
# HTML API
|
||||
|
||||
# HTML
|
||||
|
||||
All of Undum's output is HTML. This allows you to style your content
|
||||
in any way you choose. It also allows you to include rich media into
|
||||
your output, such as images, video or audio.
|
||||
|
@ -180,123 +178,3 @@ data will be passed into both sets of handlers.
|
|||
Raw links, as usual, do not have any processing performed. If they
|
||||
contain query data, it will be passed on to their target as it would
|
||||
for any link in any HTML document.
|
||||
|
||||
|
||||
# Defining Situations in HTML
|
||||
|
||||
*New in Version 2*
|
||||
|
||||
From v.2, Undum supports defining situations entirely from HTML. The
|
||||
tutorial game files show this in action, if you want to see a concrete
|
||||
example.
|
||||
|
||||
### Required Data
|
||||
|
||||
Situations defined in HTML should be diven as a `div` with
|
||||
`class="situation"` set. The content of the `div` will be turned into
|
||||
a new `SimpleSituation` (see the <a href="./API.html">API
|
||||
document</a>), with the content of the div output when the situation's
|
||||
`enter` method is called. In addition to the `class="situation"` and
|
||||
the HTML content, the `div` also requires its `id` attribute to be
|
||||
set, and the value of this id will be used as the situation id for the
|
||||
newly created situation. Situations created from HTML are instances of
|
||||
the `SimpleSituation` prototype.
|
||||
|
||||
The game scans the HTML file for situations, compiles them and adds
|
||||
them to the main `game.situation` dictionary. Because the situations
|
||||
end up in the same place, you can freely mix the two methods, defining
|
||||
some situations in HTML, and others in Javascript. For this reason,
|
||||
you can't have a situation defined in the HTML with the same id as one
|
||||
in your Javascript file. This will raise an error.
|
||||
|
||||
### Optional Data
|
||||
|
||||
In addition to the id and content of the situation, additional options
|
||||
can be set by defining one or more of the following `data-` attributes
|
||||
on the `div`. Each is interpreted and passed to a corresponding option
|
||||
on a `SimpleSituation` object, so to find more information on what
|
||||
each value means, see the <a href="./API.html">Javascript API</a>.
|
||||
|
||||
#### data-option-text
|
||||
|
||||
If defined, this specifies the label that will be used when the
|
||||
situation appears in an choice block. In Javascript, this can be
|
||||
either fixed text, or a function. In the HTML API, only fixed text is
|
||||
supported.
|
||||
|
||||
#### data-can-view
|
||||
|
||||
If defined, this should be the body of a function that will be
|
||||
compiled and attached to the situation's canView method. The
|
||||
content of this attribute will be wrapped with:
|
||||
|
||||
(function(character, system, situation) {
|
||||
... HTML attribute ...
|
||||
})
|
||||
|
||||
to make the final function. So, your definition should end with a
|
||||
`return` statement. For example:
|
||||
|
||||
<div id="situation-id-1" class="situation"
|
||||
data-can-view="return character.qualities.foo == 2">
|
||||
|
||||
This is intended to be similar to the way browsers function with event
|
||||
handlers on HTML tags, such as `onClick`. The actual semantics are
|
||||
difficult to replicate exactly, and there may be use-cases that are
|
||||
impossible, but for most uses, this will do the right thing.
|
||||
|
||||
#### data-can-choose
|
||||
|
||||
If defined, this should be the body of a function that will be
|
||||
compiled and attached to the situations canChoose method. See the
|
||||
description of `canView`, above, for details of how the value in this
|
||||
attribute is interpreted.
|
||||
|
||||
#### data-priority
|
||||
|
||||
If given, this is parsed as a number and set as the situation's
|
||||
`priority` value.
|
||||
|
||||
#### data-frequency
|
||||
|
||||
If given, this is parsed as a number and set as the situation's
|
||||
`frequency` value.
|
||||
|
||||
#### data-display-order
|
||||
|
||||
If given, this is parsed as a number and set as the situation's
|
||||
`displayOrder` value.
|
||||
|
||||
#### data-tags
|
||||
|
||||
If given this should be a set of tags to label the situation with. The
|
||||
string is split at commas, spaces and tabs. So "foo, bar cube
|
||||
dock-trog" is parsed as four tags: "foo", "bar", "cube" and
|
||||
"dock-trog".
|
||||
|
||||
#### data-heading
|
||||
|
||||
If given, then this heading will be used as the `heading` property for
|
||||
the SimpleSituation. If no `data-option-text` is given, the heading
|
||||
will also be used in choice blocks.
|
||||
|
||||
#### data-choices
|
||||
|
||||
If given, this should be a list of items to use in generating an
|
||||
implicit set of situation choices, exactly as for the `choices`
|
||||
property of `SimpleSituation`. The values of this list is parsed
|
||||
exactly as for `data-tags`, above, splitting at commas, spaces and
|
||||
tags.
|
||||
|
||||
#### data-min-choices
|
||||
|
||||
If `data-choices` is given, this value can also be specified. If so,
|
||||
it is interpreted as an integer and passed to the `minChoices` option
|
||||
of `SimpleSituation`.
|
||||
|
||||
|
||||
#### data-max-choices
|
||||
|
||||
If `data-choices` is given, this value can also be specified. If so,
|
||||
it is interpreted as an integer and passed to the `maxChoices` option
|
||||
of `SimpleSituation`.
|
50
en/README.md
50
en/README.md
|
@ -1 +1,49 @@
|
|||
# Undum 2 documentation
|
||||
# High Level Overview
|
||||
|
||||
Undum games are based around three concepts: Situations, Actions and
|
||||
Qualities.
|
||||
|
||||
## Situations
|
||||
|
||||
A situation is a chunk of code that is responsible for adding content
|
||||
to the screen and responding to user interaction. All user interaction
|
||||
is performed by clicking links in the content.
|
||||
|
||||
Often a link will change the current situation, in which case another
|
||||
situation is loaded, can write to the screen, and can begin responding
|
||||
to user interaction. When a situation changes, all links that were
|
||||
previously available are removed, so that the player can't unfairly go
|
||||
back and try alternative options after committing to one. It is
|
||||
possible to override this behavior, see the section on 'Sticky',
|
||||
below.
|
||||
|
||||
There is always exactly one active situation. These situations, and
|
||||
the links between them, form the structure of the game.
|
||||
|
||||
## Actions
|
||||
|
||||
A situation may offer the player a series of actions to perform. These
|
||||
actions are internal to that situation and normally do not cause the
|
||||
situation to change. Actions may output more content, including new
|
||||
links for the user to select.
|
||||
|
||||
## Qualities
|
||||
|
||||
Qualities represent the current state of the character. Internally
|
||||
they are all numeric values, able to take on any decimal value,
|
||||
positive or negative. They have no meaning to Undum - they are given
|
||||
meaning by your code as you perform calculations or make decisions
|
||||
based on their value.
|
||||
|
||||
Qualities display themselves to the user through a formatting
|
||||
function, which can turn the number into any kind of indicator: a
|
||||
progress bar, a symbol, a word, an integer, and so on. So as far as
|
||||
the user is concerned, qualities can represent any kind of value.
|
||||
|
||||
## Other Concepts
|
||||
|
||||
There are a handful of other elements to an Undum game, but they are
|
||||
very much in a supporting role. Quality groups allow you to display a
|
||||
set of qualities under a common heading; and character text is a short
|
||||
chunk of HTML that you can use to summarize a character's qualities,
|
||||
or to give hints.
|
||||
|
|
|
@ -1,4 +1,15 @@
|
|||
# Summary
|
||||
|
||||
* [Javascript API](api.md)
|
||||
* [Creating an Undum Game](creating.md)
|
||||
* [Game Definition](/game_definition.md)
|
||||
* [Implicit Choices](implicit.md)
|
||||
* [Generating Choices](/generating_choices.md)
|
||||
* [HTML API](HTML.md)
|
||||
* [Defining Situations in HTML](/defining_situations_in_html.md)
|
||||
* [Javascript API](API.md)
|
||||
* [Character](/character.md)
|
||||
* [System](/system.md)
|
||||
* [Situation](/random.md)
|
||||
* [Translation and Internationalization](i18n.md)
|
||||
* [Loading and Saving](files.md)
|
||||
|
||||
|
|
41
en/character.md
Normal file
41
en/character.md
Normal file
|
@ -0,0 +1,41 @@
|
|||
# `Character`
|
||||
|
||||
The character is created for you, but is passed into most of the
|
||||
functions that you define. It consists of an object with no methods
|
||||
and two properties:
|
||||
|
||||
#### `qualities`
|
||||
|
||||
The qualities object maps quality identifiers to their current
|
||||
value. Your code finds the current value associated with a quality by
|
||||
reading from this object, for example:
|
||||
|
||||
var gold = character.qualities.gold;
|
||||
|
||||
To set a quality, you have two choices. If you know the quality you
|
||||
want to set will not appear in the user interface, then you can set it
|
||||
directly:
|
||||
|
||||
character.qualities.gold += 1;
|
||||
|
||||
If it does appear on-screen, then this approach will mean that the
|
||||
character panel doesn't update, and the screen will be out of sync
|
||||
with the actual value. Instead it is better to use the `System` method
|
||||
`setQuality`, which also updates the UI:
|
||||
|
||||
system.setQuality('gold', character.qualities.gold+1);
|
||||
|
||||
It is fine to use `setQuality` if the quality isn't visible, making
|
||||
this the preferred option for all quality modifications.
|
||||
|
||||
#### `sandbox`
|
||||
|
||||
Not every bit of data you want to associate with a character fits
|
||||
nicely into a quality. The sandbox is a general storage space for any
|
||||
further data you want to store in the course of your game, for
|
||||
example:
|
||||
|
||||
character.sandbox.roomsSearched.push('bathroom');
|
||||
|
||||
Sandbox data is never visible to the user, so you can use any data
|
||||
structures you like here, to any depth.
|
206
en/creating.md
206
en/creating.md
|
@ -1,6 +1,6 @@
|
|||
# Creating an Undum Game
|
||||
|
||||
# File Structure
|
||||
## File Structure
|
||||
|
||||
An Undum game consists of a single HTML file. This imports the game
|
||||
engine and any supporting files. It also provides the structure needed
|
||||
|
@ -57,207 +57,3 @@ you to have the best of both worlds. HTML Situations are discussed in
|
|||
the page on the <a href="./HTML.html">HTML API</a>.
|
||||
|
||||
|
||||
## The Game Definition File
|
||||
|
||||
The game definition file where you create your game. To define a game
|
||||
you must provide the following data:
|
||||
|
||||
* A unique ID for the game, which is used to make sure saved games
|
||||
don't get confused.
|
||||
|
||||
* A version number that allows you to manage upgrades to your
|
||||
content.
|
||||
|
||||
* All the Situations that make up your game.
|
||||
|
||||
* The identifier of the situation that starts the game.
|
||||
|
||||
In addition it is very common to provide the following data:
|
||||
|
||||
* Descriptions of each quality your game will use, and how that should
|
||||
be displayed to the player.
|
||||
|
||||
* Definitions of what groups of qualities should appear in the
|
||||
character panel and what headings to use to label them.
|
||||
|
||||
* An Initialization function that sets up the game ready for
|
||||
playing. This is where you typically assign any starting qualities
|
||||
to the character, or set their initial character text.
|
||||
|
||||
And finally, there are a range of other data you can provide:
|
||||
|
||||
* Functions to be called whenever any situation is entered, or exited.
|
||||
|
||||
* Functions to be called before or after any action is carried out.
|
||||
|
||||
### Identifiers
|
||||
|
||||
Identifiers are small snippets of text that allow you to refer to
|
||||
something in Undum. There are two types of identifier. The Game
|
||||
identifier represents your whole game, and has its own particular
|
||||
requirements (described below).
|
||||
|
||||
Lots of other things in Undum have identifiers (Situations, Actions,
|
||||
Qualities, Quality Groups), and they all have the same
|
||||
requirements. These identifiers must consist of Latin lower-case
|
||||
letters (i.e. a-z, no accents), hyphens, and the digits 0-9 only.
|
||||
|
||||
### Game ID
|
||||
|
||||
The game identifier should be a string that is unlikely to be used in
|
||||
other games. You could use a UUID (my preference), or you could use a
|
||||
variation on your email `mygame-myname@mydomain.com`, or a URL you
|
||||
control `http://mydomain.com/undum-games/mygame`. If and when Undum
|
||||
games end up being re-distributable (as I hope they will), having a
|
||||
universally unique identifier will mean that saved games don't clash.
|
||||
|
||||
As stated previously, the game identifier doesn't have the same
|
||||
requirements as any other identifier in Undum, you can use any
|
||||
characters to make up your game ID.
|
||||
|
||||
### Version Number
|
||||
|
||||
The version number is a string of text that indicates what version of
|
||||
the content is in the file. There is no set format for this version
|
||||
text, so you can use any scheme that suits you. I have used the
|
||||
"major.minor" approach.
|
||||
|
||||
Like the Game ID, this value is used to make sure that saved games
|
||||
don't clash. If you change you content, then previous saved games may
|
||||
not work correctly. By updating the version number, you allow the
|
||||
player to be notified of this directly, rather than suffering a
|
||||
silent crash. The effect of this is that you don't need to update the
|
||||
version number if you make a change to something that doesn't alter
|
||||
the structure of the game. If you just change some text, for example,
|
||||
or add an extra action that merely outputs a piece of description.
|
||||
|
||||
### Situation List
|
||||
|
||||
Situations are defined in a Javascript object, placed in the
|
||||
`undum.game.situations` property. Situations in the object use their
|
||||
situation identifier as a property name, and a `Situation` object as
|
||||
its value. For example:
|
||||
|
||||
undum.game.situations = {
|
||||
doorway: new Situation(...),
|
||||
lobby: new SimpleSituation(...),
|
||||
lobby-upstairs-closed: new MyCustomSituation(...),
|
||||
... etc ...
|
||||
};
|
||||
|
||||
The situation objects are described more fully below.
|
||||
|
||||
### Starting Situation
|
||||
|
||||
This is placed in the `undum.game.start` property. It should consist
|
||||
of the situation identifier as a string. It must be given.
|
||||
|
||||
### Qualities
|
||||
|
||||
Qualities don't have to be displayed to the user. They can just
|
||||
function as internal properties for use by your code. Qualities that
|
||||
will never be displayed don't need to be declared, you can just set
|
||||
them when you need them (we'll look at the API for setting qualities
|
||||
below).
|
||||
|
||||
Often you want the quality to be displayed, however, and so you need
|
||||
to tell Undum to display the quality, and how it should be
|
||||
formatted. The `QualityDefinition` object does that. Any quality that
|
||||
doesn't have a corresponding quality definition will be invisible to
|
||||
the player.
|
||||
|
||||
Quality definitions are placed in an object in the
|
||||
`undum.game.qualities` property. Within this object, the property
|
||||
names are the quality identifiers, and the values they contain are
|
||||
`QualityDefinition` objects. For example:
|
||||
|
||||
undum.game.qualities = {
|
||||
investigation: new IntegerQuality("Investigation", ...),
|
||||
"found-mr-black": new OnOffQuality("Found Mr. Black", ...),
|
||||
... etc ...
|
||||
};
|
||||
|
||||
There are a number of `QualityDefinition` constructors defined which
|
||||
automatically format in common ways, you can also define your own and
|
||||
take complete control of the output. We'll return to discussion of the
|
||||
API, below.
|
||||
|
||||
### Quality Groups
|
||||
|
||||
Qualities can be assigned to groups, and displayed under a common
|
||||
heading in the character panel. To define groups, place an object in
|
||||
the `undum.game.qualityGroups` property. This object should have
|
||||
properties which are the group identifiers, and values that are
|
||||
`QualityGroup` objects. For example:
|
||||
|
||||
undum.game.qualityGroups = {
|
||||
stats: new QualityGroup(...),
|
||||
clues: new QualityGroup(...),
|
||||
equipment: new QualityGroup(...)
|
||||
}
|
||||
|
||||
A common source of puzzlement is that you don't use this data
|
||||
structure to define which qualities belong in which group. Instead,
|
||||
each quality that you want to assign to a group, should be given the
|
||||
identifier of the group it belongs to. So your `undum.game.qualities`
|
||||
property will look something like:
|
||||
|
||||
undum.game.qualities = {
|
||||
investigation: new IntegerQuality("Investigation", {group:'stats'}),
|
||||
"found-mr-black": new OnOffQuality("Found Mr. Black", {group:'clues'}),
|
||||
... etc ...
|
||||
};
|
||||
|
||||
Again, see the API documentation below for more details about what you
|
||||
can pass into these constructors.
|
||||
|
||||
### Initialization Function
|
||||
|
||||
Your initialization function should be placed in the `undum.game.init`
|
||||
property. Normally its job is to configure the character at the start
|
||||
of the game. For example:
|
||||
|
||||
undum.game.init = function(character, system) {
|
||||
character.qualities.investigating = 0;
|
||||
character.qualities.money = 100;
|
||||
... etc ...
|
||||
system.setCharacterText(...);
|
||||
};
|
||||
|
||||
Initialization functions can, but normally doesn't, output
|
||||
text. Instead the starting situation is tasked with outputting the
|
||||
initial content.
|
||||
|
||||
### Global Event Functions
|
||||
|
||||
Most of the time you want Situations to handle user
|
||||
interaction. Occasionally, however, you have to handle something that
|
||||
spans situations. It would be inconvenient to duplicate the same code
|
||||
in every situation. So Undum provides a set of hooks for you to
|
||||
respond globally to user interaction. There are five of these:
|
||||
`enter`, `afterEnter`, `exit`, `beforeAction` and `afterAction`. You
|
||||
can define functions in your game file using the properties:
|
||||
`undum.game.enter`, `undum.game.afterEnter`,
|
||||
`undum.game.exit`, `undum.game.beforeAction`, and
|
||||
`undum.game.afterAction`.
|
||||
|
||||
The `enter`, `afterEnter`, and `exit` functions look like this:
|
||||
|
||||
undum.game.enter = function(character, system, from, to) {
|
||||
...
|
||||
};
|
||||
|
||||
where `from` and `to` are the identifiers of the situations being left
|
||||
and entered, respectively. And the `beforeAction` and `afterAction`
|
||||
functions look like this:
|
||||
|
||||
undum.game.beforeAction = function(character, system, situation, action) {
|
||||
...
|
||||
};
|
||||
|
||||
where `situation` is the current situation identifier, and `action` is
|
||||
the identifier of the action being carried out.
|
||||
|
||||
These functions intentionally look like the `enter`, `exit` and `act`
|
||||
methods of the `Situation` object. These are described in more detail
|
||||
in the API reference.
|
||||
|
|
118
en/defining_situations_in_html.md
Normal file
118
en/defining_situations_in_html.md
Normal file
|
@ -0,0 +1,118 @@
|
|||
# Defining Situations in HTML
|
||||
|
||||
*New in Version 2*
|
||||
|
||||
From v.2, Undum supports defining situations entirely from HTML. The
|
||||
tutorial game files show this in action, if you want to see a concrete
|
||||
example.
|
||||
|
||||
### Required Data
|
||||
|
||||
Situations defined in HTML should be diven as a `div` with
|
||||
`class="situation"` set. The content of the `div` will be turned into
|
||||
a new `SimpleSituation` (see the <a href="./API.html">API
|
||||
document</a>), with the content of the div output when the situation's
|
||||
`enter` method is called. In addition to the `class="situation"` and
|
||||
the HTML content, the `div` also requires its `id` attribute to be
|
||||
set, and the value of this id will be used as the situation id for the
|
||||
newly created situation. Situations created from HTML are instances of
|
||||
the `SimpleSituation` prototype.
|
||||
|
||||
The game scans the HTML file for situations, compiles them and adds
|
||||
them to the main `game.situation` dictionary. Because the situations
|
||||
end up in the same place, you can freely mix the two methods, defining
|
||||
some situations in HTML, and others in Javascript. For this reason,
|
||||
you can't have a situation defined in the HTML with the same id as one
|
||||
in your Javascript file. This will raise an error.
|
||||
|
||||
### Optional Data
|
||||
|
||||
In addition to the id and content of the situation, additional options
|
||||
can be set by defining one or more of the following `data-` attributes
|
||||
on the `div`. Each is interpreted and passed to a corresponding option
|
||||
on a `SimpleSituation` object, so to find more information on what
|
||||
each value means, see the <a href="./API.html">Javascript API</a>.
|
||||
|
||||
#### data-option-text
|
||||
|
||||
If defined, this specifies the label that will be used when the
|
||||
situation appears in an choice block. In Javascript, this can be
|
||||
either fixed text, or a function. In the HTML API, only fixed text is
|
||||
supported.
|
||||
|
||||
#### data-can-view
|
||||
|
||||
If defined, this should be the body of a function that will be
|
||||
compiled and attached to the situation's canView method. The
|
||||
content of this attribute will be wrapped with:
|
||||
|
||||
(function(character, system, situation) {
|
||||
... HTML attribute ...
|
||||
})
|
||||
|
||||
to make the final function. So, your definition should end with a
|
||||
`return` statement. For example:
|
||||
|
||||
<div id="situation-id-1" class="situation"
|
||||
data-can-view="return character.qualities.foo == 2">
|
||||
|
||||
This is intended to be similar to the way browsers function with event
|
||||
handlers on HTML tags, such as `onClick`. The actual semantics are
|
||||
difficult to replicate exactly, and there may be use-cases that are
|
||||
impossible, but for most uses, this will do the right thing.
|
||||
|
||||
#### data-can-choose
|
||||
|
||||
If defined, this should be the body of a function that will be
|
||||
compiled and attached to the situations canChoose method. See the
|
||||
description of `canView`, above, for details of how the value in this
|
||||
attribute is interpreted.
|
||||
|
||||
#### data-priority
|
||||
|
||||
If given, this is parsed as a number and set as the situation's
|
||||
`priority` value.
|
||||
|
||||
#### data-frequency
|
||||
|
||||
If given, this is parsed as a number and set as the situation's
|
||||
`frequency` value.
|
||||
|
||||
#### data-display-order
|
||||
|
||||
If given, this is parsed as a number and set as the situation's
|
||||
`displayOrder` value.
|
||||
|
||||
#### data-tags
|
||||
|
||||
If given this should be a set of tags to label the situation with. The
|
||||
string is split at commas, spaces and tabs. So "foo, bar cube
|
||||
dock-trog" is parsed as four tags: "foo", "bar", "cube" and
|
||||
"dock-trog".
|
||||
|
||||
#### data-heading
|
||||
|
||||
If given, then this heading will be used as the `heading` property for
|
||||
the SimpleSituation. If no `data-option-text` is given, the heading
|
||||
will also be used in choice blocks.
|
||||
|
||||
#### data-choices
|
||||
|
||||
If given, this should be a list of items to use in generating an
|
||||
implicit set of situation choices, exactly as for the `choices`
|
||||
property of `SimpleSituation`. The values of this list is parsed
|
||||
exactly as for `data-tags`, above, splitting at commas, spaces and
|
||||
tags.
|
||||
|
||||
#### data-min-choices
|
||||
|
||||
If `data-choices` is given, this value can also be specified. If so,
|
||||
it is interpreted as an integer and passed to the `minChoices` option
|
||||
of `SimpleSituation`.
|
||||
|
||||
|
||||
#### data-max-choices
|
||||
|
||||
If `data-choices` is given, this value can also be specified. If so,
|
||||
it is interpreted as an integer and passed to the `maxChoices` option
|
||||
of `SimpleSituation`.
|
1
en/file_structure.md
Normal file
1
en/file_structure.md
Normal file
|
@ -0,0 +1 @@
|
|||
# File Structure
|
|
@ -1,7 +1,5 @@
|
|||
# Loading and Saving
|
||||
|
||||
# Loading and Saving
|
||||
|
||||
There is no API for you to manually access loading and saving
|
||||
functionality. The load and save functions are triggered by the
|
||||
buttons on the user interface. But the way loading and saving work
|
||||
|
|
204
en/game_definition.md
Normal file
204
en/game_definition.md
Normal file
|
@ -0,0 +1,204 @@
|
|||
# The Game Definition File
|
||||
|
||||
The game definition file where you create your game. To define a game
|
||||
you must provide the following data:
|
||||
|
||||
* A unique ID for the game, which is used to make sure saved games
|
||||
don't get confused.
|
||||
|
||||
* A version number that allows you to manage upgrades to your
|
||||
content.
|
||||
|
||||
* All the Situations that make up your game.
|
||||
|
||||
* The identifier of the situation that starts the game.
|
||||
|
||||
In addition it is very common to provide the following data:
|
||||
|
||||
* Descriptions of each quality your game will use, and how that should
|
||||
be displayed to the player.
|
||||
|
||||
* Definitions of what groups of qualities should appear in the
|
||||
character panel and what headings to use to label them.
|
||||
|
||||
* An Initialization function that sets up the game ready for
|
||||
playing. This is where you typically assign any starting qualities
|
||||
to the character, or set their initial character text.
|
||||
|
||||
And finally, there are a range of other data you can provide:
|
||||
|
||||
* Functions to be called whenever any situation is entered, or exited.
|
||||
|
||||
* Functions to be called before or after any action is carried out.
|
||||
|
||||
### Identifiers
|
||||
|
||||
Identifiers are small snippets of text that allow you to refer to
|
||||
something in Undum. There are two types of identifier. The Game
|
||||
identifier represents your whole game, and has its own particular
|
||||
requirements (described below).
|
||||
|
||||
Lots of other things in Undum have identifiers (Situations, Actions,
|
||||
Qualities, Quality Groups), and they all have the same
|
||||
requirements. These identifiers must consist of Latin lower-case
|
||||
letters (i.e. a-z, no accents), hyphens, and the digits 0-9 only.
|
||||
|
||||
### Game ID
|
||||
|
||||
The game identifier should be a string that is unlikely to be used in
|
||||
other games. You could use a UUID (my preference), or you could use a
|
||||
variation on your email `mygame-myname@mydomain.com`, or a URL you
|
||||
control `http://mydomain.com/undum-games/mygame`. If and when Undum
|
||||
games end up being re-distributable (as I hope they will), having a
|
||||
universally unique identifier will mean that saved games don't clash.
|
||||
|
||||
As stated previously, the game identifier doesn't have the same
|
||||
requirements as any other identifier in Undum, you can use any
|
||||
characters to make up your game ID.
|
||||
|
||||
### Version Number
|
||||
|
||||
The version number is a string of text that indicates what version of
|
||||
the content is in the file. There is no set format for this version
|
||||
text, so you can use any scheme that suits you. I have used the
|
||||
"major.minor" approach.
|
||||
|
||||
Like the Game ID, this value is used to make sure that saved games
|
||||
don't clash. If you change you content, then previous saved games may
|
||||
not work correctly. By updating the version number, you allow the
|
||||
player to be notified of this directly, rather than suffering a
|
||||
silent crash. The effect of this is that you don't need to update the
|
||||
version number if you make a change to something that doesn't alter
|
||||
the structure of the game. If you just change some text, for example,
|
||||
or add an extra action that merely outputs a piece of description.
|
||||
|
||||
### Situation List
|
||||
|
||||
Situations are defined in a Javascript object, placed in the
|
||||
`undum.game.situations` property. Situations in the object use their
|
||||
situation identifier as a property name, and a `Situation` object as
|
||||
its value. For example:
|
||||
|
||||
undum.game.situations = {
|
||||
doorway: new Situation(...),
|
||||
lobby: new SimpleSituation(...),
|
||||
lobby-upstairs-closed: new MyCustomSituation(...),
|
||||
... etc ...
|
||||
};
|
||||
|
||||
The situation objects are described more fully below.
|
||||
|
||||
### Starting Situation
|
||||
|
||||
This is placed in the `undum.game.start` property. It should consist
|
||||
of the situation identifier as a string. It must be given.
|
||||
|
||||
### Qualities
|
||||
|
||||
Qualities don't have to be displayed to the user. They can just
|
||||
function as internal properties for use by your code. Qualities that
|
||||
will never be displayed don't need to be declared, you can just set
|
||||
them when you need them (we'll look at the API for setting qualities
|
||||
below).
|
||||
|
||||
Often you want the quality to be displayed, however, and so you need
|
||||
to tell Undum to display the quality, and how it should be
|
||||
formatted. The `QualityDefinition` object does that. Any quality that
|
||||
doesn't have a corresponding quality definition will be invisible to
|
||||
the player.
|
||||
|
||||
Quality definitions are placed in an object in the
|
||||
`undum.game.qualities` property. Within this object, the property
|
||||
names are the quality identifiers, and the values they contain are
|
||||
`QualityDefinition` objects. For example:
|
||||
|
||||
undum.game.qualities = {
|
||||
investigation: new IntegerQuality("Investigation", ...),
|
||||
"found-mr-black": new OnOffQuality("Found Mr. Black", ...),
|
||||
... etc ...
|
||||
};
|
||||
|
||||
There are a number of `QualityDefinition` constructors defined which
|
||||
automatically format in common ways, you can also define your own and
|
||||
take complete control of the output. We'll return to discussion of the
|
||||
API, below.
|
||||
|
||||
### Quality Groups
|
||||
|
||||
Qualities can be assigned to groups, and displayed under a common
|
||||
heading in the character panel. To define groups, place an object in
|
||||
the `undum.game.qualityGroups` property. This object should have
|
||||
properties which are the group identifiers, and values that are
|
||||
`QualityGroup` objects. For example:
|
||||
|
||||
undum.game.qualityGroups = {
|
||||
stats: new QualityGroup(...),
|
||||
clues: new QualityGroup(...),
|
||||
equipment: new QualityGroup(...)
|
||||
}
|
||||
|
||||
A common source of puzzlement is that you don't use this data
|
||||
structure to define which qualities belong in which group. Instead,
|
||||
each quality that you want to assign to a group, should be given the
|
||||
identifier of the group it belongs to. So your `undum.game.qualities`
|
||||
property will look something like:
|
||||
|
||||
undum.game.qualities = {
|
||||
investigation: new IntegerQuality("Investigation", {group:'stats'}),
|
||||
"found-mr-black": new OnOffQuality("Found Mr. Black", {group:'clues'}),
|
||||
... etc ...
|
||||
};
|
||||
|
||||
Again, see the API documentation below for more details about what you
|
||||
can pass into these constructors.
|
||||
|
||||
### Initialization Function
|
||||
|
||||
Your initialization function should be placed in the `undum.game.init`
|
||||
property. Normally its job is to configure the character at the start
|
||||
of the game. For example:
|
||||
|
||||
undum.game.init = function(character, system) {
|
||||
character.qualities.investigating = 0;
|
||||
character.qualities.money = 100;
|
||||
... etc ...
|
||||
system.setCharacterText(...);
|
||||
};
|
||||
|
||||
Initialization functions can, but normally doesn't, output
|
||||
text. Instead the starting situation is tasked with outputting the
|
||||
initial content.
|
||||
|
||||
### Global Event Functions
|
||||
|
||||
Most of the time you want Situations to handle user
|
||||
interaction. Occasionally, however, you have to handle something that
|
||||
spans situations. It would be inconvenient to duplicate the same code
|
||||
in every situation. So Undum provides a set of hooks for you to
|
||||
respond globally to user interaction. There are five of these:
|
||||
`enter`, `afterEnter`, `exit`, `beforeAction` and `afterAction`. You
|
||||
can define functions in your game file using the properties:
|
||||
`undum.game.enter`, `undum.game.afterEnter`,
|
||||
`undum.game.exit`, `undum.game.beforeAction`, and
|
||||
`undum.game.afterAction`.
|
||||
|
||||
The `enter`, `afterEnter`, and `exit` functions look like this:
|
||||
|
||||
undum.game.enter = function(character, system, from, to) {
|
||||
...
|
||||
};
|
||||
|
||||
where `from` and `to` are the identifiers of the situations being left
|
||||
and entered, respectively. And the `beforeAction` and `afterAction`
|
||||
functions look like this:
|
||||
|
||||
undum.game.beforeAction = function(character, system, situation, action) {
|
||||
...
|
||||
};
|
||||
|
||||
where `situation` is the current situation identifier, and `action` is
|
||||
the identifier of the action being carried out.
|
||||
|
||||
These functions intentionally look like the `enter`, `exit` and `act`
|
||||
methods of the `Situation` object. These are described in more detail
|
||||
in the API reference.
|
50
en/generating_choices.md
Normal file
50
en/generating_choices.md
Normal file
|
@ -0,0 +1,50 @@
|
|||
# Generating Choices
|
||||
## Generating Choice HTML
|
||||
|
||||
Thew new `System.writeChoices` method allows you to give a list of
|
||||
situation id's and have Undum generate a standard looking block of
|
||||
choices.
|
||||
|
||||
It does this by asking each choice how it prefers to be displayed, by
|
||||
calling its `optionText` method. This allows situtions to change how
|
||||
they are displayed depending on the current state of the character.
|
||||
|
||||
Also called is the situations `canChoose` method. This will normally
|
||||
return true, but if it returns false, the option will still be
|
||||
displayed, but not as a link, and will not be clickable. This allows
|
||||
you to show the player that an option would be available, if they did
|
||||
something else first, such as increase a quality.
|
||||
|
||||
On its own `System.writeChoices` is still mostly manual: it finds the
|
||||
link text for you, and builds the HTML, but you still have to give it
|
||||
a set of situation ids that you want for your choices.
|
||||
|
||||
## Generating Choices
|
||||
|
||||
Undum now also provides the `System.getSituationIdChoices` method which automatically compiles a list of situation ids, which can then be passed to `System.writeChoices` for display.
|
||||
This method is powerful and complex, so we'll explore its use in increasing depth.
|
||||
|
||||
## Generating Choices by Tags
|
||||
|
||||
Situations now can have one or more tags associated with them. You can
|
||||
ask `System.getSituationIdChoices` to return the ids of any situtions
|
||||
that match a tag. This allows you to easily build decisions that you
|
||||
can extend later. You might have a 'chapter' tag, and you mark each
|
||||
situation which begins a chapter using this tag, you can then do.
|
||||
|
||||
system.getSituationIdChoices(['#chapter'])
|
||||
|
||||
to return all chapter choices.
|
||||
|
||||
The way tags are processed tries to be intelligent. You can match on
|
||||
more than one tag, and any situation matching either tag will be
|
||||
returned, but each situation will be returned no more than once. You
|
||||
can even mix tags and explicit situation ids:
|
||||
|
||||
system.getSituationIdChoices(['#chapter', 'introduction', '#endmatter'])
|
||||
|
||||
When you only need to pass one tag to `System.getSituationIdChoices`
|
||||
you can do so without using a list, so the first example above could
|
||||
be equally written:
|
||||
|
||||
system.getSituationIdChoices('#chapter')
|
|
@ -1,4 +1,3 @@
|
|||
|
||||
# Translation and Internationalization
|
||||
|
||||
Undum provides support for translations and internationalization.
|
||||
|
|
|
@ -1,7 +1,5 @@
|
|||
# New Choice System
|
||||
|
||||
# New Choice System
|
||||
|
||||
*New in Version 2*
|
||||
|
||||
In version one of Undum, all links from one situation to another had
|
||||
|
@ -20,59 +18,6 @@ quickly build the links to new situations in the standard HTML format
|
|||
a list of situations that are available, given the current state of
|
||||
the game.
|
||||
|
||||
# Generating Choice HTML
|
||||
|
||||
Thew new `System.writeChoices` method allows you to give a list of
|
||||
situation id's and have Undum generate a standard looking block of
|
||||
choices.
|
||||
|
||||
It does this by asking each choice how it prefers to be displayed, by
|
||||
calling its `optionText` method. This allows situtions to change how
|
||||
they are displayed depending on the current state of the character.
|
||||
|
||||
Also called is the situations `canChoose` method. This will normally
|
||||
return true, but if it returns false, the option will still be
|
||||
displayed, but not as a link, and will not be clickable. This allows
|
||||
you to show the player that an option would be available, if they did
|
||||
something else first, such as increase a quality.
|
||||
|
||||
On its own `System.writeChoices` is still mostly manual: it finds the
|
||||
link text for you, and builds the HTML, but you still have to give it
|
||||
a set of situation ids that you want for your choices.
|
||||
|
||||
# Generating Choices
|
||||
|
||||
Undum now also provides the `System.getSituationIdChoices` method
|
||||
which automatically compiles a list of situation ids, which can then
|
||||
be passed to `System.writeChoices` for display. This method is
|
||||
powerful and complex, so we'll explore its use in increasing depth.
|
||||
|
||||
## Generating Choices by Tags
|
||||
|
||||
Situations now can have one or more tags associated with them. You can
|
||||
ask `System.getSituationIdChoices` to return the ids of any situtions
|
||||
that match a tag. This allows you to easily build decisions that you
|
||||
can extend later. You might have a 'chapter' tag, and you mark each
|
||||
situation which begins a chapter using this tag, you can then do.
|
||||
|
||||
system.getSituationIdChoices(['#chapter'])
|
||||
|
||||
to return all chapter choices.
|
||||
|
||||
The way tags are processed tries to be intelligent. You can match on
|
||||
more than one tag, and any situation matching either tag will be
|
||||
returned, but each situation will be returned no more than once. You
|
||||
can even mix tags and explicit situation ids:
|
||||
|
||||
system.getSituationIdChoices(['#chapter', 'introduction', '#endmatter'])
|
||||
|
||||
When you only need to pass one tag to `System.getSituationIdChoices`
|
||||
you can do so without using a list, so the first example above could
|
||||
be equally written:
|
||||
|
||||
system.getSituationIdChoices('#chapter')
|
||||
|
||||
|
||||
## Ordering Choices
|
||||
|
||||
Choices returned by `System.getSituationIdChoices` will be ordered
|
||||
|
|
71
en/index.md
71
en/index.md
|
@ -1,71 +0,0 @@
|
|||
# Home
|
||||
|
||||
# Contents
|
||||
|
||||
## <a href="./introduction.html">High level overview</a>
|
||||
|
||||
Describes the concepts that go into an Undum game, and how they
|
||||
interact.
|
||||
|
||||
## <a href="./creating.html">Creating an Undum Game</a>
|
||||
|
||||
Describes the files you need to create to make an Undum game, and what
|
||||
needs to go into them.
|
||||
|
||||
## <a href="./implicit.html">Implicit Choices</a>
|
||||
|
||||
Version 2 of Undum includes a new framework for automatically
|
||||
generating choices for the player, based on information stored in
|
||||
situations.
|
||||
|
||||
## <a href="./HTML.html">HTML API</a>
|
||||
|
||||
Undum games use HTML to output text and media, but has some
|
||||
constraints on the HTML you can use. Undum also provides built-in
|
||||
behavior tied to specific HTML classes that you can use in your
|
||||
output. In v.2, Undum also added support for defining many kinds of
|
||||
situation entirely in HTML, with no Javascript needed.
|
||||
|
||||
## <a href="./API.html">Javascript API</a>
|
||||
|
||||
A complete breakdown of the API exposed to your code via
|
||||
Javascript. This details the methods that you call to output content,
|
||||
find random numbers and translate your game.
|
||||
|
||||
## <a href="./i18n.html">Translation and Internationalization</a>
|
||||
|
||||
Describes Undum's core translation system, and how you can create
|
||||
games that support multiple languages.
|
||||
|
||||
## <a href="./files.html">Loading and Saving</a>
|
||||
|
||||
Undum has an unusual way of supporting loading and saving of games, to
|
||||
support a wide range of browsers, sites and game styles. This document
|
||||
contains the technical details, and how this affects you as a game
|
||||
author.
|
||||
|
||||
|
||||
# Undum Changelog
|
||||
|
||||
## 2011-05-27
|
||||
|
||||
- Added `System.writeBefore` to do out of order insertion. (credit:
|
||||
ekyrath)
|
||||
|
||||
- Added an optional selector to `System.write` and
|
||||
`System.writeBefore` to support out of order insertion. (credit:
|
||||
ekyrath)
|
||||
|
||||
- Removed the use of `__defineGetter__`, so that the core code now
|
||||
works on IE7 (thanks for the bug report juhana and bloomengine).
|
||||
|
||||
## 2011-08-18
|
||||
|
||||
- Added support for functions in the `content` and `header` of a
|
||||
`SimpleSituation` (credit: David Eyk).
|
||||
|
||||
## 2013-09-27
|
||||
|
||||
- Updated to v.2, including support for <a
|
||||
href="./implicit.html">implicit choices</a> and <a
|
||||
href="./HTML.html">HTML-defined situations</a>.
|
398
en/random.md
Normal file
398
en/random.md
Normal file
|
@ -0,0 +1,398 @@
|
|||
# `Situation`
|
||||
|
||||
The `Situation` object is the prototype of all the situations in your
|
||||
game. It can be used directly, or through its more common derived
|
||||
type, `SimpleSituation`. The base `Situation` gives you maximum
|
||||
flexibility, but `SimpleSituation` provides more functionality and can
|
||||
produce terser code.
|
||||
|
||||
#### `new Situation(options)`
|
||||
|
||||
Creates a new situation. The options array can specify your
|
||||
implementation for any or all of the following methods of this class:
|
||||
|
||||
- `enter`
|
||||
- `exit`
|
||||
- `act`
|
||||
- `optionText`
|
||||
- `canView`
|
||||
- `canChoose`
|
||||
|
||||
(see below for explanations of those methods). This allows
|
||||
you to easily create situations that override certain behaviors with
|
||||
code such as:
|
||||
|
||||
Situation({
|
||||
enter: function(character, system, from) {
|
||||
... your implementation ...
|
||||
}
|
||||
});
|
||||
|
||||
without having to subclass `Situation` to provide your own
|
||||
implementations.
|
||||
|
||||
In addition the following options can be passed in.
|
||||
|
||||
- `tags`: A list of tags with which to label this situation. These are
|
||||
primarily used to generate implicit lists of choices with
|
||||
`System.getSituationIdChoices`. Tags are arbitrary strings. You can
|
||||
pass a list of strings, or a single string. If you pass a single
|
||||
string, it will be split at spaces, commas and tabs to form a list of
|
||||
tags. For this reason, tags normally do not contain spaces, commas or
|
||||
tabs (though if you pass in a list, and don't expect Undum to do the
|
||||
splitting for you, you can include any characters you like in a tag).
|
||||
|
||||
- `optionText` (as a string): If given as a string, rather than a
|
||||
function, this text will be returned whenever `optionText(...)` is
|
||||
called.
|
||||
|
||||
- `displayOrder`: A numeric value, defaults to 1. When displaying
|
||||
lists of implicitly generated choices, the options be displayed in
|
||||
increasing value of this parameter.
|
||||
|
||||
- `priority`: Can be any number, defaults to 1. When generating lists
|
||||
of choices implicitly, situations are considered in descending
|
||||
priority order. If higher priority situations can be displayed, lower
|
||||
priority situations will be hidden. See `System.getSituationIdChoices`
|
||||
for details of the algorithm.
|
||||
|
||||
- `frequency`: Any number, defaults to 1. When generating lists of
|
||||
implicit choices, where there are more choices available that slots to
|
||||
display them, situations will be chosen randomly, with a probability
|
||||
based on this value. See `System.getSituationIdChoices` for details of
|
||||
the algorithm.
|
||||
|
||||
#### `enter(character, system, from)`
|
||||
|
||||
This is called when Undum enters a situation. The `character` and
|
||||
`system` are instances of `Character` and `System` as described
|
||||
above. The `from` parameter is a string containing the situation
|
||||
identifier for the situation that we're arriving from.
|
||||
|
||||
This method is the most commonly overridden. It is commonly used to
|
||||
describe the current situation (by sending content to
|
||||
`system.write()`) and to update the character (by calling
|
||||
`system.setQuality()` or by changing data in the character's `sandbox`
|
||||
object)..
|
||||
|
||||
#### `exit(character, system, to)`
|
||||
|
||||
This method takes the same `character` and `system` parameters as
|
||||
`enter`. Its third parameter, `to`, is a string containing the
|
||||
identifier of the situation we're exiting to.
|
||||
|
||||
#### `act(character, system, action)`
|
||||
|
||||
This method again takes the same `character` and `system` parameters
|
||||
as before. Its third parameter is a string containing the action
|
||||
identifier corresponding to the link the player clicked. It is common
|
||||
to use an `if` statement or a `switch` to query this action identifier
|
||||
and decide what to do accordingly. For situations in which many
|
||||
different actions are possible, consider using the `SimpleSituation`
|
||||
prototype, which provides this switching behavior for you.
|
||||
|
||||
#### `optionText(character, system, hostSituation)`
|
||||
|
||||
This method is called by `System.writeChoices` to generate a label for
|
||||
links to this situation. The `hostSituation` is the situation that has
|
||||
asked for the choices to be displayed.
|
||||
|
||||
#### `canView(character, system, hostSituation)`
|
||||
|
||||
This method is called by `System.getSituationIdChoices` to determine
|
||||
whether this situation can be part of a list of choices in the current
|
||||
game state. It should return true or false.
|
||||
|
||||
#### `canChoose(character, system, hostSituation)`
|
||||
|
||||
This method is called by `System.writeChoices` to determine whether a
|
||||
link should be added to allow the user to enter this situation. If
|
||||
not, the choice will still appear, but will not be clickable.
|
||||
|
||||
|
||||
|
||||
## SimpleSituation
|
||||
|
||||
This prototype builds on the basic `Situation`, providing tools to
|
||||
make it easy to output content in the `enter` method, and to switch
|
||||
between different functions depending on the action identifier passed
|
||||
into the `act` method. The `exit` method of `SimpleSituation` is
|
||||
exactly as for the base type `Situation`.
|
||||
|
||||
#### `new SimpleSituation(content, options)`
|
||||
|
||||
Creates a new simple situation that will display the given content
|
||||
when its `enter` method is called. The given options dictionary
|
||||
provides further control of the behavior of this type. Valid options
|
||||
are:
|
||||
|
||||
- `enter`: Providing an enter function in the `options` parameter
|
||||
allows you to add additional behavior to the enter method. Your
|
||||
custom function will be called *in addition to* and *after* the
|
||||
default content is written to the screen. You cannot override
|
||||
`SimpleSituation`'s `enter` method by providing this function. To
|
||||
override the method, you would have to create a derived type. If
|
||||
you provide an `enter` function, it should have the same form as
|
||||
`Situation.enter`.
|
||||
|
||||
- `act`: Pass in a function to add additional behavior to the act
|
||||
method. As for `enter`, your method is called *in addition to* and
|
||||
*after* the built-in functionality.
|
||||
|
||||
- `exit`: Because `SimpleSituation` has no default behavior for
|
||||
`exit`, any function you pass in here will be the only exit
|
||||
behavior for the object you are creating.
|
||||
|
||||
- `heading`: The `content` that you specify will be written out
|
||||
verbatim. You can include headings in this content. Often it is
|
||||
more convenient to pass in just the text in the `content`
|
||||
parameter. In that case you may define this `heading` parameter to
|
||||
display a heading before the text. Unlike `content`, this doesn't
|
||||
need to conform to the Display Content requirements.
|
||||
|
||||
- `actions`: This should be an object that maps action identifiers to
|
||||
responses. A response should be either some Display Content to
|
||||
write to the screen, or a function that will process that
|
||||
request. These functions should have the same signature as the
|
||||
`Situation.act` method. Each function will only be called if the
|
||||
situation receives a call to `act` with its corresponding
|
||||
identifier. This allows you to simply define functions that only
|
||||
get called when particular actions happen.
|
||||
|
||||
- `choices`: An optional list of tags and situation-ids, with tags
|
||||
prefixed by a has symbol to distinguish them from situation ids. If
|
||||
given, this will cause the SimpleSituation to output an implicit block
|
||||
of choices after the content.
|
||||
|
||||
- `minChoices`: If you have given a `choices` definition, you can set
|
||||
this to an integer value to change the number of choices that will
|
||||
appear. See `System.getSituationIdChoices` for more information on
|
||||
how this affects the output.
|
||||
|
||||
- `maxChoices`: If you have given a `choices` definition, you can set
|
||||
this to an integer value to change the number of choices that will
|
||||
appear. See `System.getSituationIdChoices` for more information on
|
||||
how this affects the output.
|
||||
|
||||
An example `SimpleSituation` definition might be:
|
||||
|
||||
new SimpleSituation(
|
||||
"<p>...content...</p>",
|
||||
{
|
||||
heading: "Title",
|
||||
actions: {
|
||||
listen: function(character, system, action) {
|
||||
if (character.qualities.hearing > 5) {
|
||||
system.write("<p>You hear a tinkling inside.</p>");
|
||||
} else {
|
||||
system.write("<p>You hear nothing.</p>");
|
||||
}
|
||||
},
|
||||
search: "<p>You find nothing.</p>"
|
||||
}
|
||||
}
|
||||
);
|
||||
|
||||
notice how the `listen` function is responsible for its own output,
|
||||
where the `search` property is a string in Display Content format,
|
||||
ready for output.
|
||||
|
||||
#### Functions in `SimpleSituation`
|
||||
|
||||
Both the `content` and the `heading` of a simple situation can be
|
||||
provided either as plain text, or as a function. If you provide a
|
||||
function, then it will be called with no arguments, and it should
|
||||
return a string to use for the output. This enables `SimpleSituation`
|
||||
to be used with other formatting and templating systems.
|
||||
|
||||
## QualityDefinition
|
||||
|
||||
Quality definitions tell Undum how and where to display a quality in
|
||||
the character panel. Each quality definition has one method, `format`,
|
||||
which is responsible for converting a numeric quality value into a
|
||||
displayable quantity.
|
||||
|
||||
You define your qualities in your `undum.game.qualities` property.
|
||||
|
||||
|
||||
#### `new QualityDefinition(title, options)`
|
||||
|
||||
Creates a new `QualityDefinition`. It is rare to call this constructor
|
||||
yourself, most often one of the derived types of `QualityDefinition`
|
||||
are used. They are defined below.
|
||||
|
||||
The `title` should be a string, and can contain HTML. It is used to
|
||||
label the quality in the character panel. It can be any string, it
|
||||
doesn't have to be in Display Content format.
|
||||
|
||||
Options are passed in in the `options` parameter. The following
|
||||
options are available.
|
||||
|
||||
- `priority`: A string used to sort qualities within their
|
||||
groups. When the system displays a list of qualities they will be
|
||||
sorted by this string. If you don't give a priority, then the title
|
||||
will be used, so you'll get alphabetic order. Normally you either
|
||||
don't give a priority, or else use a priority string containing
|
||||
0-padded numbers (e.g. "00001").
|
||||
|
||||
- `group`: The identifier of a group in which to display this
|
||||
parameter. If a group is given, then it must be defined in your
|
||||
`undum.game.qualityGroups` property.
|
||||
|
||||
- `extraClasses`: These classes will be attached to the `<div>` tag
|
||||
that surrounds the quality when it is displayed. A common use for
|
||||
this is to add icons representing the quality. In your CSS define a
|
||||
class for each icon, then pass those classes into the appropriate
|
||||
quality definitions.
|
||||
|
||||
#### `format(character, value)`
|
||||
|
||||
This is called by Undum to get a human readable string representing
|
||||
the given quality value for the given character. The method may return
|
||||
an empty string if the value has no need to be displayed, or it may
|
||||
return `null` if the quantity itself shouldn't be displayed. The
|
||||
difference here is significant. If your `QualityDefinition` returns
|
||||
the empty string, then the quality will appear in the character panel,
|
||||
but it will have no value marked. If it returns `null`, then it will
|
||||
be removed from the character panel entirely.
|
||||
|
||||
Most commonly the `character` parameter is ignored, but in your own
|
||||
derived types you can take advantage of being able to access other
|
||||
information about the character.
|
||||
|
||||
You may call this function yourself, but there is commonly no need. It
|
||||
will be called by Undum any time the corresponding quality needs to be
|
||||
displayed.
|
||||
|
||||
### `IntegerQuality`
|
||||
|
||||
This is a derived type of `QualityDefinition` that displays the
|
||||
quality value by rounding it down to the nearest integer. This is
|
||||
ideal for most numeric statistics.
|
||||
|
||||
### `NonZeroIntegerQuality`
|
||||
|
||||
This is a derived type of `IntegerQuality` that only displays its
|
||||
value when it is non-zero. If it is non-zero then it formats in the
|
||||
same way as `IntegerQuality`. Whereas `IntegerQuality` whould show
|
||||
zero values as '0', this type of quality displays nothing.
|
||||
|
||||
### `NumericQuality`
|
||||
|
||||
This is a derived type of `QualityDefinition` that displays the
|
||||
quality value directly, as a full floating point value.
|
||||
|
||||
### `WordScaleQuality`
|
||||
|
||||
Sometimes you want qualities displayed in words rather than
|
||||
numbers. This is a derived type of `QualityDefinition` that allows you
|
||||
to define words corresponding to possible quality values.
|
||||
|
||||
#### `new WordScaleQuality(title, words, options)`
|
||||
|
||||
The `title` parameter is exactly as for `QualityDefinition`.
|
||||
|
||||
The `words` parameter determines what words will be used. It should be
|
||||
an array of strings. By default the first string will be used to
|
||||
represent a value of zero (after rounding down), and the second string
|
||||
a value of 1, and so on to the end of the array. Values outside the
|
||||
array are treated differently depending on the value of `useBonuses`
|
||||
in the `options` parameter.
|
||||
|
||||
The `options` parameter supports the same three options as
|
||||
`QualityDefinition`. It also takes the following additional
|
||||
parameters:
|
||||
|
||||
- `offset`: With offset=0 (the default), a quantity value of 0 will
|
||||
map to the first word, and so on. If offset is non-zero then the
|
||||
value given will correspond to the first word in the list. So if
|
||||
offset=4, then the first word in the list will be used for value=4,
|
||||
the second for value=5. You can specify a non-integer offset value,
|
||||
in this case the offset is applied *before* the value is rounded
|
||||
down.
|
||||
|
||||
- `useBonuses`: If this is true (the default), then values outside the
|
||||
range of words will be constructed from the word and a numeric
|
||||
bonus. So with offset=0 and five words, the last of which is
|
||||
'amazing', a score of six would give 'amazing+1'. if this is
|
||||
false, then the bonus would be omitted, so anything beyond
|
||||
'amazing' is still 'amazing'.
|
||||
|
||||
### `FudgeAdjectivesQuality`
|
||||
|
||||
This is a derived type of `WordScaleQuality` that doesn't require you
|
||||
to specify the words you wish to use. It uses the word scale from the
|
||||
Fudge RPG: "terrible", "poor", "mediocre", "fair", "good", "great" and
|
||||
"superb".
|
||||
|
||||
#### `new FudgeAdjectivesQuality(title, options)`
|
||||
|
||||
The parameters `title` and `options` are as for the `WordScaleQuality`
|
||||
constructor. The `offset` option defaults to -3, however (in
|
||||
`WordScaleQuality` it defaults to 0), making "fair" the display value
|
||||
for 0.
|
||||
|
||||
### `OnOffQuality`
|
||||
|
||||
An `OnOffQuality` returns `null` from its `format` method
|
||||
(i.e. removes itself from the character panel) when the corresponding
|
||||
quality value is zero. Otherwise it returns the empty string (i.e. it
|
||||
is shown in the panel, but doesn't have a value label). See
|
||||
`QualityDisplay.format` above for more details on this distinction.
|
||||
|
||||
#### `new OnOffQuality(title, options)`
|
||||
|
||||
The constructor for this type is the same as for `QualityDefinition`
|
||||
from which it is derived. It accepts one extra option:
|
||||
|
||||
- `onDisplay`: If given, then rather than displaying the empty string,
|
||||
it displays the given string when its corresponding value is
|
||||
non-zero. This can be used to display a check-mark, for example
|
||||
(`{onDisplay:"✓"}`), or even a HTML `img` tag.
|
||||
|
||||
### YesNoQuality
|
||||
|
||||
A `YesNoQuality` displays one of two strings depending whether its
|
||||
value is zero or not.
|
||||
|
||||
#### `new YesNoQuality(title, options)`
|
||||
|
||||
The constructor for this type is the same as for `QualityDefinition`
|
||||
from which it is derived. It accepts two extra options:
|
||||
|
||||
- `yesDisplay`, `noDisplay`: Either or both of these may be given. If
|
||||
they are given, then they should be set to a string, which will be
|
||||
used to indicate non-zero or zero values, respectively. By default
|
||||
"yes" and "no" are used.
|
||||
|
||||
## `QualityGroup`
|
||||
|
||||
A quality group defines a set of qualities that should be displayed
|
||||
together in the character panel, under an optional subheading. You
|
||||
could use quality groups to distinguish between qualities representing
|
||||
a character's innate abilities and their equipment, for example.
|
||||
|
||||
You define your quality groups in your `undum.game.qualityGroups`
|
||||
property.
|
||||
|
||||
|
||||
#### `new QualityGroup(title, options)`
|
||||
|
||||
Constructs a new quality group that will have the given `title` for a
|
||||
subheading. The title may be `null`, indicating that this group does
|
||||
not need a heading.
|
||||
|
||||
The `options` parameter should be an object with the given optional
|
||||
parameters:
|
||||
|
||||
- `priority`: A string used to sort quality groups. When the system
|
||||
displays more than one quality group, they will be sorted by this
|
||||
string. If you don't give a priority, then the title will be used,
|
||||
so you'll get alphabetic order. Normally you either don't give a
|
||||
priority, or else use a priority string containing 0-padded numbers
|
||||
(e.g. "00001").
|
||||
|
||||
- `extraClasses`: These classes will be attached to the `<div>` tag
|
||||
that surrounds the entire quality group when it is displayed. You
|
||||
can use this in addition to your CSS to radically change the way
|
||||
certain qualities are displayed.
|
247
en/system.md
Normal file
247
en/system.md
Normal file
|
@ -0,0 +1,247 @@
|
|||
# `System`
|
||||
|
||||
The system represents the interface between your code and the
|
||||
user-interface. You don't create your own `System` object, it is
|
||||
passed into your code.
|
||||
|
||||
#### `clearContent(elementSelector)`
|
||||
|
||||
*Since version 2*
|
||||
|
||||
Removes all content from the page, clearing the main content area.
|
||||
|
||||
Although Undum is designed to keep the flow of the narrative on one
|
||||
page, sometimes you do need to start a new page, and this allows you
|
||||
to do so.
|
||||
|
||||
The `elementSelector` is options. If you give it, then the DOM element
|
||||
matching the selector is cleared, rather than the whole document.
|
||||
|
||||
#### `write(content, elementSelector)`
|
||||
|
||||
Writes new content to the main flow of the story. The content you pass
|
||||
in must be either valid DOM elements already, or else be a string
|
||||
containing text in Display Content format.
|
||||
|
||||
The `elementSelector` is optional. If you provide it, then the new
|
||||
content will be added after the DOM element in the document that
|
||||
matches the selector. This allows you to do out-of-order addition of
|
||||
content. Simply add a paragraph with an id in your game, then later
|
||||
you can give this id as a selector to write, and the new content will
|
||||
be inserted immediately following that paragraph, regardless of how
|
||||
much extra content has been added since that point. If no selector is
|
||||
given then `#content` is used, i.e. the content is added at the end of
|
||||
the document. The `writeBefore` method inserts content at the start of
|
||||
the document, or before a selector.
|
||||
|
||||
The story will scroll to the start of the insertion point. If you do
|
||||
not wish to animate this scrolling, but just jump right there, you can
|
||||
switch off jQuery's animation system by adding `jQuery.fx.off=true` to
|
||||
your initialization code. This is particularly useful when debugging.
|
||||
|
||||
#### `writeHeading(content, elementSelector)`
|
||||
|
||||
Writes new content into the story and formats it as a heading. This
|
||||
method work exactly as `write`, but wraps the content you provide into
|
||||
a `h1` html tag.
|
||||
|
||||
#### `writeBefore(content, elementSelector)`
|
||||
|
||||
Writes content into the story. This method is identical to `write`,
|
||||
above, except that the content is written at the start of the story,
|
||||
or if a selector is given, inserted before the matching element. On
|
||||
browsers that support it, the story will be scrolled to the insertion
|
||||
point.
|
||||
|
||||
#### `writeChoices(listOfSituationIds)`
|
||||
|
||||
*Since version 2*
|
||||
|
||||
Creates a standard block of choices, one for each of the given
|
||||
situation ids. The text used in the links will be whatever is returned
|
||||
by the situation's `optionText` method. In addition, if the
|
||||
situation's `canChoose` method returns `false`, then the option will
|
||||
be displayed, but will not be clickable.
|
||||
|
||||
#### `getSituationIdChoices(listOfIdsOrTags, minChoices, maxChoices)`
|
||||
|
||||
*Since version 2*
|
||||
|
||||
This function is a complex and powerful way of compiling implicit
|
||||
situation choices. You give it a list of situation ids and situation
|
||||
tags. Tags should be prefixed with a hash # to differentiate them from
|
||||
situation ids. The function then considers all matching situations in
|
||||
descending priority order, calling their canView functions and
|
||||
filtering out any that should not be shown, given the current
|
||||
state. Without additional parameters the function returns a list of
|
||||
the situation ids at the highest level of priority that has any valid
|
||||
results. So, for example, if a tag #places matches three situations,
|
||||
one with priority 2, and two with priority 3, and all of them can be
|
||||
viewed in the current context, then only the two with priority 3 will
|
||||
be returned. This allows you to have high-priority situations that
|
||||
trump any lower situations when they are valid, such as situations
|
||||
that force the player to go to one destination if the player is out of
|
||||
money, for example.
|
||||
|
||||
If a `minChoices` value is given, then the function will attempt to
|
||||
return at least that many results. If not enough results are available
|
||||
at the highest priority, then lower priorities will be considered in
|
||||
turn, until enough situations are found. In the example above, if we
|
||||
had a minChoices of three, then all three situations would be
|
||||
returned, even though they have different priorities. If you need to
|
||||
return all valid situations, regardless of their priorities, set
|
||||
minChoices to a large number, such as `Number.MAX_VALUE`, and leave
|
||||
maxChoices undefined.
|
||||
|
||||
If a `maxChoices` value is given, then the function will not return any
|
||||
more than the given number of results. If there are more than this
|
||||
number of results possible, then the highest priority resuls will be
|
||||
guaranteed to be returned, but the lowest priority group will have to
|
||||
fight it out for the remaining places. In this case, a random sample
|
||||
is chosen, taking into account the frequency of each situation. So a
|
||||
situation with a frequency of 100 will be chosen 100 times more often
|
||||
than a situation with a frequency of 1, if there is one space
|
||||
available. Often these frequencies have to be taken as a guideline,
|
||||
and the actual probabilities will only be approximate. Consider three
|
||||
situations with frequencies of 1, 1, 100, competing for two
|
||||
spaces. The 100-frequency situation will be chosen almost every time,
|
||||
but for the other space, one of the 1-frequency situations must be
|
||||
chosen. So the actual probabilities will be roughly 50%, 50%,
|
||||
100%. When selecting more than one result, frequencies can only be a
|
||||
guide.
|
||||
|
||||
Before this function returns its result, it sorts the situations in
|
||||
increasing order of their `displayOrder` properties.
|
||||
|
||||
|
||||
#### `doLink(URL)`
|
||||
|
||||
Carries out the action associated with the given URL, as if it had
|
||||
been the `href` of a HTML link that the user clicked. This allows you
|
||||
to procedurally change situation and carry out actions from your code.
|
||||
|
||||
#### `rnd`
|
||||
|
||||
This holds a general purpose random number generator. It is an object
|
||||
derived from the `Random` prototype, so see `Random` below for details
|
||||
on its API.
|
||||
|
||||
#### `time`
|
||||
|
||||
This is a numeric value holding the current time, in seconds, since
|
||||
the player began playing the game. This value is correctly propagated
|
||||
across saves, so it is the only way you should track timing. In
|
||||
particular you should never call `new Date()` and use that value to
|
||||
determine the outcome of any event. You can use the current date to
|
||||
display the current date, for example, but not to control what actions
|
||||
or situations are available. See the section on Loading and Saving for
|
||||
more details of why this is important.
|
||||
|
||||
#### `setQuality(qualityId, newValue)`
|
||||
|
||||
Sets the character's given quality to the given value. This function
|
||||
also updates the character panel, animating the change in value if
|
||||
that is necessary. Do not directly set quality values in the
|
||||
character, because the user-interface will not detect and reflect
|
||||
those changes.
|
||||
|
||||
#### `animateQuality(qualityId, newValue, options)`
|
||||
|
||||
Like `setQuality`, this function changes the current value of the
|
||||
given quality. In addition, however, it displays a progress bar that
|
||||
shows to the user how the value has changed. The `options` parameter
|
||||
should be an object containing options for how the bar should
|
||||
display. The available options are:
|
||||
|
||||
- `from`: The proportion along the progress bar where the animation
|
||||
starts. Defaults to 0, valid range is 0-1.
|
||||
|
||||
- `to`: The proportion along the progress bar where the animation
|
||||
ends. Defaults to 1, valid range is 0-1.
|
||||
|
||||
- `showValue`: If `true` (the default) then the new value of the
|
||||
quality is displayed above the progress bar.
|
||||
|
||||
- `displayValue`: If this is given, and `showValue` is `true`, then
|
||||
the given value is used above the progress bar. If this isn't
|
||||
given, and `showValue` is `true`, then the display value will be
|
||||
calculated from the `QualityDefinition`, as normal. This option is
|
||||
useful for qualities that don't have a definition, because they
|
||||
don't normally appear in the UI.
|
||||
|
||||
- `title`: The title of the progress bar. If this is not given, then
|
||||
the title of the quality is used. As for `displayValue` this is
|
||||
primarily used when the progress bar doesn't have a
|
||||
`QualityDefinition`, and therefore doesn't have a title.
|
||||
|
||||
- `leftLabel`, `rightLabel`: Underneath the progress bar you can place
|
||||
two labels at the left and right extent of the track. These can
|
||||
help to give scale to the bar. So if the bar signifies going from
|
||||
10.2 to 10.5, you might label the left and right extents with "10"
|
||||
and "11" respectively and have the `from` and `to` value be 0.2 and
|
||||
0.5 respectively. If these are not given, then the labels will be
|
||||
omitted.
|
||||
|
||||
#### `setCharacterText(content)`
|
||||
|
||||
Sets the block of character text that appears in the character
|
||||
panel. As for the `write` method, this text should be either valid DOM
|
||||
elements, or a string meeting the Display Content requirements.
|
||||
|
||||
#### `clearLinks(URL)`
|
||||
|
||||
Call this function with an Undum link URL (e.g. `ballroom`, or
|
||||
`ballroom/open-cabinet`). It will remove all occurrences of that link
|
||||
from the page. This is equivalent to what happens when you change
|
||||
situation, or when you click a link marked with the `once` CSS
|
||||
class. It allows you to control what options are available
|
||||
dynamically, from your code.
|
||||
|
||||
## `Random`
|
||||
|
||||
The `Random` object provides a set of tools for simple random number
|
||||
generation, in a way that is guaranteed to work with the Loading and
|
||||
Saving functionality in Undum. An instance of `Random` is provided in
|
||||
the `rnd` property of the `System` object, so you will never need to
|
||||
create your own. It has the following methods:
|
||||
|
||||
#### `random()`
|
||||
|
||||
Generates a random number between 0 and 1, where 0 is inclusive, and 1
|
||||
is exclusive. You can use this to check against known probabilities,
|
||||
such as:
|
||||
|
||||
if (system.rnd.random() > 0.5) {
|
||||
...
|
||||
}
|
||||
|
||||
To check for a 50/50 chance.
|
||||
|
||||
#### `randomInt(min, max)`
|
||||
|
||||
Return a random number between the given two values, where both values
|
||||
are inclusive. So `randomInt(2,3)` generates either 2 or 3.
|
||||
|
||||
#### `dice(n, dx, plus)`
|
||||
|
||||
Rolls _n_ dice with _dx_ sides and adds _plus_ to the result. This
|
||||
allows you to easily get results for rolls from regular RPG-style
|
||||
games, such as 3d6+2. The `plus` parameter may be negative or
|
||||
positive.
|
||||
|
||||
#### `aveDice(n, plus)`
|
||||
|
||||
Rolls _n_ averaging dice, and adds _plus_ to the result. Averaging dice
|
||||
are a special type of d6 with sides marked [2,3,3,4,4,5]. They represent
|
||||
the fact that most people are fairly average, and results should not lie
|
||||
at the extremes.
|
||||
|
||||
#### `diceString(definition)`
|
||||
|
||||
Rolls dice according to the given definition string. The string should
|
||||
be of the form xdy+z, where the x component and z component are
|
||||
optional. This rolls x dice of with y sides, and adds z to the result,
|
||||
the z component can also be negative: xdy-z. The y component can be
|
||||
either a number of sides, or can be the special values 'F', for a
|
||||
fudge die (with 3 sides, +,0,-), '%' for a 100 sided die, or 'A' for
|
||||
an averaging die (with sides 2,3,3,4,4,5).
|
Loading…
Reference in a new issue