undum2-docs/en/random.md

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.