Story
Game world modeling using Tapestry commands. These commands include the description of scenes, kinds of objects, specific nouns and their properties, the placement and relation between nouns, and so on.
Most authors will probably prefer the "jess" plain English style of modeling over these more explicit commands. However, there are some commands -- like defining scenes -- which don't have a corollary within jess.
Definitions:
String Types:
- Relation Cardinality: Used as part of [DefineRelation] to declare a new kind of relationship between nouns.
Slots:
- Story Statement: Story commands model the game world.
- Field Definition: Describe the members of kinds, records, patterns, and so on.
Commands:
- Aspect:[initially:] A field containing a set of states.
- Bool:[initially:] A field containing a boolean ( true/false ) value.
- Define action:requires:[provides:] Defines an in-game behavior that can be triggered by an actor.
- Define kind:ancestor: Defines a new kind: a set of properties used by game objects.
- Define kind:fields: Adds properties to an existing kind.
- Define kind:rule:[named:]do: Adds an "event listener" which only runs if the target of the triggered action a noun of the specified kind.
- Define noun:kind: Ensures that a noun of the specified name and kind exists in the world.
- Define noun:rule:[named:]do: Adds an "event listener" which only runs if the target of the triggered action is the specified noun.
- Define noun:states: Assigns one or more initial states to a existing noun.
- Define noun:value:initially: Assigns an initial value to a existing noun.
- Define pattern:provides: Adds one or more local variable to an existing pattern.
- Define pattern:requires:provides:[do:] Declares a new pattern.
- Define relation:kind:otherKind:cardinality: Defines a connection between different kinds of nouns.
- Define relative:nouns:otherNouns: Relate nouns to each other.
- Define rule:[named:]do: Change the behavior of an existing pattern.
- Define scene:[requires:][with:] Defines a collection of nouns, kinds, game rules, etc.
- Define singular:plural: Controls how Tapestry pluralize words.
- Define state:names: Defines a set of mutually exclusive states that can be assigned to any kind of noun.
- Define test:[requires:][scene:]do: Defines a scene used for testing a story.
- Interpret:with: Creates a grammar used to parse player input.
- Interpret alias:as: Interpret a name typed by the player as some existing noun.
- Interpret name:with: Creates a grammar to parse player input that can be referenced in other grammars.
- Is count:of: A guard which returns true based on a counter.
- Note: Used for the blockly editor so that hash-mark style comments are visible in the editor.
- Nothing: A valueless field.
- Num:[initially:] A field containing a single number.
- NumList:[initially:] A field containing a list of numbers.
- Record:kind:[initially:] A field containing a single record.
- RecordList:kind:[initially:] A field containing a list of records.
- Say: Print templated text.
- Say response:with: Print text in a replaceable manner.
- Text:[kind:][initially:] A field containing a single piece of text.
- TextList:[kind:][initially:] A field containing a list of text.
String Types
Relation Cardinality
Used as part of [DefineRelation] to declare a new kind of relationship between nouns. The options are:
Commands
A field containing a set of states. Aspects are defined using the {"Define state:names:"} command.
Slots:
Terms:
A field containing a boolean ( true/false ) value. As a special case, when used to define a boolean field in a kind, the boolean becomes a state set consisting of the state and its opposite. For instance, a boolean field called "reasonable" generates a set called "reasonable status" and the states "reasonable" and "not reasonable."
Slots:
Terms:
Defines an in-game behavior that can be triggered by an actor. Actions are a special kind of pattern, and like patterns use "rules" to define and customize their behavior. The shared library includes many common actions including things like moving from room to room, examining something, taking or dropping items, and so on. See the Tapestry guide for more information.
Slots:
Terms:
| action: | TextEval | A unique name for the action. |
| requires: | FieldDefinition repeats | Parameters to customize the behavior of an action. Most actions require an actor, and possibly one or two other objects. For instance: the standard "storing" action -- used for inserting something into a container -- requires an actor to perform the action, an object to store, and a container to receive that object. |
| provides: optional | FieldDefinition repeats | A list of any local variables needed by the action carry out its behavior. |
Defines a new kind: a set of properties used by game objects. This command is similar to a sentence like: "Doors are a kind of opener."
Slots:
Terms:
Adds properties to an existing kind. This command is similar to a sentence like: "Things have some text called a description."
Slots:
Terms:
| kind: | TextEval | The name of the kind to which the fields will be assigned. |
| fields: | FieldDefinition repeats | One or more fields to add to the kind. |
Adds an "event listener" which only runs if the target of the triggered action a noun of the specified kind. See [DefineRule] for more information.
Slots:
Terms:
Ensures that a noun of the specified name and kind exists in the world.
Slots:
Terms:
Adds an "event listener" which only runs if the target of the triggered action is the specified noun. See [DefineRule] for more information.
Slots:
Terms:
Assigns one or more initial states to a existing noun.
Slots:
Terms:
| noun: | TextEval | The name of an existing noun. |
| states: | TextListEval | The state names to assign to the noun. The states must be part of a state set used by the noun's kind or one of its ancestor kinds. |
Assigns an initial value to a existing noun.
Slots:
Terms:
| noun: | TextEval | The name of an existing noun. |
| value: | TextEval | The name of the property to set. ( The property must have been defined by the noun's kind or one of its ancestor kinds. ) |
| initially: | Assignment | The value to assign the noun. The type of the value must match the type of the property. ( ie. Text values can't be assigned to number properties, etc. ) |
Adds one or more local variable to an existing pattern.
Slots:
Terms:
| pattern: | TextEval | The name of an existing pattern. |
| provides: | FieldDefinition repeats | One or more variables that the pattern can use to carry out its goals. |
Declares a new pattern. A pattern is a set of author defined rules used at runtime to either change the game world, or to provide information about it. Patterns are the Tapestry equivalent of functions.
Slots:
Terms:
| pattern: | TextEval | A unique name for the pattern. |
| requires: | FieldDefinition repeats | Parameters a caller can specify when triggering the pattern. Despite the name, whether the parameters are actually required depends on the pattern's specific implementation. |
| provides: | FieldDefinition repeats | Local variables used by the pattern to carry out its goals. As a special case, the first provided variable also acts as a return value for the pattern. |
| do: optional | Execute repeats | The default behavior of the pattern if no other rule applies. |
Defines a connection between different kinds of nouns. The shared library, for instance, defines a spatial relation between objects; allowing one object to be placed inside another.
Slots:
Terms:
| relation: | TextEval | Unique name for the relation. |
| kind: | TextEval | The kind of nouns allowed on the "left side" of a relation. |
| otherKind: | TextEval | The kind of nouns allowed on the "right side" of a relation. |
| cardinality: | RelationCardinality | Determines the number of times a noun can appear on the left or the right side of a given relation. |
Relate nouns to each other. Most users will probably prefer defining verbs and using jess to relate nouns. For instance: "Carrying is a verb. The relation of carrying is whereabouts. Bob is carrying the pen." See the Tapestry guide for details.
Slots:
Terms:
| relative: | TextEval | The name of an existing relationship. |
| nouns: | TextListEval | The names of one or more nouns for the "left side" of this pairing. |
| otherNouns: | TextListEval | The names of one or more nouns for the "right side" of this pairing. |
Change the behavior of an existing pattern.
For patterns defined using [DefinePattern], if a rule starts with a [core.ChooseBranch] command, and none of the branches are chosen, the pattern checks the next specified rule; and so on, until the pattern finds a branch that succeeds.
For patterns defined using [DefineAction], rules behave as "event listeners". They continue to the next listener unless specifically stopped. And, by default, they only respond to actions triggered by the player.
See the Tapestry guide for more in-depth information.
Slots:
Terms:
| rule: | TextEval | The pattern and phase to which this rule applies. For event listeners, the name can start with a modifier which changes the event phase in which the rule applies: "before", "instead of", "when", "after", and "report". The modifier can be followed by the word "someone" so that it applies to all actors and not just the player. |
| named: optional | TextEval | Optionally, specify a unique name for the rule. Giving a rule a name allows it to be replaced by later rules. |
| do: | Execute repeats | The behavior of the rule. |
Defines a collection of nouns, kinds, game rules, etc. used the game. Every .tell story has its own unique scene.
Slots:
Terms:
| scene: | TextEval | A unique name for the scene. |
| requires: optional | TextListEval | One or more scenes that this scene depends on. This is a one-way dependency. This scene can reference anything defined within the required scenes; the required scenes cannot reference anything declared within this scene. Circular dependencies are prevented by weave. |
| with: optional | StoryStatement repeats | Modeling commands for the defining nouns, kinds, game rules, etc. used by this scene. |
Controls how Tapestry pluralize words. Plurals are used both at runtime and during weave to guide the interpretation of nouns and kinds. A singular word can have multiple plurals; a plural word only has one singular form. For example: "The plural of person is people." "The plural of person is persons."
Slots:
Terms:
Defines a set of mutually exclusive states that can be assigned to any kind of noun. By default, every noun with this set of states starts the game with the first state listed by this command. At runtime, a script can change to other states, ask whether a noun is in a particular state, or ask for the name of the current state from the set. Internally, these are also known as "aspects" and "traits." Many programming languages refer to these as "enumerations." See also: {"Set:state:"} and {"Object:field:"}
Slots:
Terms:
| state: | TextEval | A unique name for the set of states. |
| names: | TextListEval | The names of the states in the set. TODO: a list of containing only one state should probably automatically generate its opposite the way that [BoolField] does. |
Defines a scene used for testing a story. Tests can be executed using the `tap check` command. TODO: see https://todo.sr.ht/~ionous/tapestry/42
Slots:
Terms:
| test: | Text | A unique name for the test. |
| requires: optional | TextListEval | One or more scenes that this test depends on. Tests implicitly depend upon the scene within which they are defined. In order to reference the nouns, kinds, etc. of any other scenes in a test, that scene must be listed here. |
| scene: optional | StoryStatement repeats | Modeling commands for defining nouns, kinds, game rules, etc. used by this test. Those definitions will not be visible outside of the test ( unless this test is "required" by another. ) |
| do: | Execute repeats | One or more commands to run when checking the test. The {"Expect:"} command will trigger a test failure when an author specified condition is not met. |
Creates a grammar used to parse player input.
Slots:
Terms:
| Interpret: | Text repeats | One or more words to match against the player's input. For example, the standard "examine" action lists the words: "examine", "x", and "describe" all of which the player can use to trigger inspect a particular object. |
| with: | ScannerMaker repeats | A tree of commands used to parse subsequent words. |
Interpret a name typed by the player as some existing noun. For example, if there is a noun called "the book", the story could define an alias so that "tome" also means the book.
Slots:
Terms:
| alias: | TextListEval | One or more alternative names for a noun. |
| as: | TextEval | The noun the aliases refer to. |
Creates a grammar to parse player input that can be referenced in other grammars. It can also be used for grammars that need more flexibility in matching the initial words of a sentence ( because {"Interpret:with:"} depends on a set of fixed words. )
Slots:
Terms:
| name: | Text | A unique name which other grammars can use to refer the grammar defined by this command. |
| with: | ScannerMaker repeats | A tree of commands used to parse player input. |
A guard which returns true based on a counter. Counters start at zero and are incremented every time the guard is checked.
Slots:
Terms:
Used for the blockly editor so that hash-mark style comments are visible in the editor. Not needed when using .tell files.
Slots:
Terms:
| Note: | Lines |
A valueless field. Intended mainly as a way for patterns which don't return a value.
Slots:
Terms:
None.A field containing a single number.
Slots:
Terms:
A field containing a list of numbers.
Slots:
Terms:
| NumList: | TextEval | Name for the field. Must be unique within the set of fields (eg. within the kind.) |
| initially: optional | NumListEval | Provides a default value; an empty list if not specified. |
A field containing a single record.
Slots:
Terms:
| Record: | TextEval | Name for the field. Must be unique within the set of fields (eg. within the kind.) |
| kind: | TextEval | The name of a valid record type. |
| initially: optional | RecordEval | Provides a default value. If not specified, accessing the field in go returns nil; accessing via script returns a blank record with zero value fields. |
A field containing a list of records. All of the records in the list must be of the same type.
Slots:
Terms:
| RecordList: | TextEval | Name for the field. Must be unique within the set of fields (eg. within the kind.) |
| kind: | TextEval | The name of a valid record type. All records in the list must be of this type. |
| initially: optional | RecordListEval | Provides a default value; an empty list if not specified. |
Print templated text. Templates contain commands executed at runtime. See the Tapestry guide for more information.
Slots:
Terms:
| Say: | Lines |
Print text in a replaceable manner. Each response has a unique name and a default bit of text it responds with. The response can be changed everywhere its used by replacing that text. ( ex. by using {"Define kind:fields": "response", "name of the response"} )
The shared library uses responses for much of what it prints to the player so that stories can change the stock phrases.
Slots:
Terms:
A field containing a single piece of text. Text fields can be used to store anything from the name of a noun, the name of a state or set of states, or something to display to the player.
Slots:
Terms:
| Text: | TextEval | Name for the field. Must be unique within the set of fields (eg. within the kind.) |
| kind: optional | TextEval | A hint that this text refers to an object or some other predefined concept in the game world. |
| initially: optional | TextEval | Provides a default value; the empty string if not specified. |
A field containing a list of text.
Slots:
Terms:
| TextList: | TextEval | Name for the field. Must be unique within the set of fields (eg. within the kind.) |
| kind: optional | TextEval | A hint that the specified text might refer to an object or some other predefined concept in the game world. |
| initially: optional | TextListEval | Provides a default value; an empty list if not specified. |