1. Adventuron
Adventuron is a text-adventure game-engine for modern platforms.
Click here to see a "hello world" style adventure.
This document is a work in progress. There may be areas of ambiguity in this initial release. If you are confused by anything at all, please contact the author, and this document will be improved.
A command line usually starts with a character such as "?" or">" or a question such as "What now?".
A web based client is available at adventuron.io/play
1.1. What is a Text Adventure?
| Please skip forward to the Getting Started section if you already have a good understanding of text adventures and hate 'fluff'. |
A text adventure is a game (or experience) where the player interacts with the game environment through textual commands.
| Screenshots in this section are not taken from games created using Adventuron. Also, please see fair use section for information of screenshots used within this document. |
A text adventure, confusingly, may also feature graphics. Graphics may enhance the experience by establishing an atmosphere or by prooviding visual cues to enlighten the player with how to solve a particular puzzle.
The addition of graphics to a text adventure is loved by some, hated by others. Some prefer textual purity. Graphics of this era were necessarily primitive as they bumped their heads up the hardware constraints of early microcomputers.
In the 1980s, when a tiny fraction of today’s computer RAM and computer storage was available to game authors, there were trade-offs to be made over quality of game text and amount or quality of graphics. 30 years later, it is possible to include optional graphics and copious text without trade offs being necessary.
The "text" part of a text adventure refers to information being primarily being conveyed by text.
A graphic adventure, by comparison, generally conveys its information by graphics and the player interaction is via interacting with the graphics.
There is a somewhat fuzzy distinction between text adventure and interactive fiction. Interactive fiction generally has far fewer tropes, is very much more advanced.
8-bit British microcomputers such as the ZX Spectrum were limited to adventures of 128K in size, including graphics, so larger interactive fiction titles were simply not feasible on the platform - but authors worked around these memory constraints using a variety of methods.
1.2. Features of a "Text Adventure"
| Please skip forward to the Getting Started section if you already have a good understanding of text adventures and hate 'fluff'. |
Though not strictly required, text adventures, follow the following tropes.
Not strictly required in modern text adventures (as touch or menus may replace direct text entry), but traditionally, the main form of interaction with a text adventure is via a command line. This is generally placed at the bottom of the game screen and is manipulated by a keyboard.
Players can write anything they like within the command line area to interact with the game, but the game does not have to understand everything.
The parser is the part of the game that interprets the text entered by the player and then cute it up into chunks that can be understood by the game engine.
The most common parser for early text adventure games was the 'verb noun' parser . Sample verb-noun pairs are "take lamp", "break jar", "open window".
Adventuron supports a complex parser, but for the purposes of this document, assume that it only supports "verb noun".
The vocabulary is the set of words that the parser understands. In a simple 'verb noun' parser it is not usually necessary to categorize words. More advanced parser benefit from tagging words with their word type, so that the parser can determine the structure of a sentence. It is possible for a verb to also be a noun (e.g. light).
In Adventuron, vocabulary is provided through the vocabulary table.
Gameplay is split into a number of locations (or rooms). A location generally has a static description.
As the user enters a location, the text of the location is displayed to the player. Different game engines deal differently with entering a location. Some may clear the screen, some may append the location description to the existing text on the screen.
Older computers almost always cleared the screen between location, due to the lack of vertical space.
In Adventuron, locations are described via the locations table.
Rooms are generally connected via compass direction nativation plus a number of other standard commands (such as up, down, enter, exit). Transitions between locations may happen automatically too as the game requires.
In Adventuron, connections are handled via the navigation table.
Games typically contain a number of objects that are distributed within the game. Objects will have a description, and may also have a adjective / noun associated with them so that the user may refer to them using a textual interface.
Characters in games can be implemented via event handlers or as objects.
Depending on the style of text adventure, objects present in a location but not held by the player are usually listed in a room / location.
An adventure game engine must match the user entered text, and perform an action based upon the text. Such actions are context sensitive.
For example, "burn note" may have a number of different responses depending on the context. If the note is not present, the game should inform the player that the note is not around. If the note is present, but you do not have anything to burn it with, inform the player. If the note is present, and you have something to burn it with, then that may trigger a series of actions, such as showing text to the player, removing the note from the game, and replacing the note with another object, for example, "ashes".
Almost all adventures use an additional mechanism called an event handler. These handlers are a list of instructions to conditionally perform, typically each game turn. For example, upon entering a room with gas inside the room, the player is informed they have to leave because they cannot breath, if the player fails to leave in a certain number of turns, then the player may die.
Text adventure games feature puzzles.
The traditional style of puzzle involves blocking access to another set of locations behind an action to perform in an earlier location. These puzzles are traditionally object based. For example, a cat won’t let you into the kitchen, so perhaps the cat might be distracted if it had some wool?
Puzzles are specified using the code section, which contains a number of tables for variables, command line processing, and much more.
Text adventure games have been traditionally punative in nature. If a player follows a route not fleshed out by the game author, or simply acts in a reckless manner, death can be the result.
Death involves a game over message, and having to reload a saved game. Each death is a lesson, and the player quickly learns the rules of the game.
With careful consideration, it is possible to design adventure games without death as a mechanic.
2. Different ways create a text adventure game
| Please skip forward to the Getting Started section if you already have a good understanding of text adventures and hate 'fluff'. |
The creation of text adventure games tend to fit into one of the following categories
| Method | Description |
|---|---|
Hand Coded |
Write code by hand in programming language or machine code. Tends to be tied to one platform or significant porting work required. |
Custom Scripting Engine Based |
Write adventure game in bespoke adventure creation language. If you have interpreter for that langauge, can be instantly ported to other machines. |
Virtual Machine Based, Hand Coded |
Hand-design a game for a virtual machine, a fictional computer with bespoke op codes optimized, typically memory optimized for common adventure operations. VM based games tend to be trivial to port to other machines, with perhaps only text layout and graphics having to change. |
Virtual Machine Based, Script Engine Based |
The Infocom and Inform approach. Write games in any given language, then have a compiler spit out platform agnostic opcodes for a virtual machine. |
Database (or Table) Based |
Adventure International / Scott Adams, Quill, PAW, GAC and now Adventuron approach. Uses lookup tables representing locations, connections, triggers, objects and more, and then push all the logic into a portable client. If the databases are isolated, the code is portable. |
Adventuron is influenced by The Quill, PAW, and GAC, which were popular with hobbyist adventure authors in the 1980s. These tools required a very basic knowledge of programming concepts and as such were suitable for learning basic computing as well as game design skills.
The greatest criticism levelled at the database approach was that adventures could start to feel a little bit samey. The constraints were tight in many of these engines and the parsers very basic.
PAW, with its more advanced parser, was a huge step forward, but even PAW faced some of this type of criticism. It is a testament to the design of PAW that Adventuron in its first incarnation is unlikely to match PAW for sheer flexibility.
Infocom adventures by comparison used a different approach. Instead of games being defined in a database, they were defined using bespoke program code, that operated in a virtual machine.
Adventuron is intended to be relatively easy to use for beginners, and to have the editor instantly accessible on the web. For complete flexibility, Inform 7 is highly recommended.
2.1. Getting Started
Adventuron uses a text file to describe the adventure game. As of the initial release, a single text file is used to describe all aspects of the game. Adventuron uses a new object notation language to represent its language. Non textual assets, such as graphics, must be converted into textual representations. The suffix for an adventuron adventure is '.adventuron'.
The tutorial segment of this document details basic funtionality only. There are many many options which will not be documented in this first release. See the appendices for more information.
A web based client is available at adventuron.io/play
The following is a basic adventure with a single location, no objects, and a single command that is understood.
"drink wine" will win the game.
################################## ## The start location ################################## start_location = throne_room ################################## ## All locations in adventure ################################## locations [] { throne_room : location "You are in the throneroom. The sacred wine is here."; } ################################## ## The Game Logic ################################## code { t1_on_input[] { : match "drink wine" { : if (is_at "throne_room") { : stagger "You drink the sacred wine.\nYou are at peace once again.\nCongratulations, you have completed the game." ; : end_game ; } } } }
3. Tutorial
3.1. Adding rooms
The only requirement of an adventure is that it defines a single location, and nominates that location as the start location.
To add a location to the adventure, simply add items to the locations block of the configuration.
The game must have at least one location, and the 'start_location' attribute must be provided at root level. The order in which locations are listed is not important.
start_location = living_room rooms { living_room : location "You are in a comfortable living room."; kitchen : location "You are in a small yet well arranged kitchen."; hallway : location "You are in a cold hallway."; }
3.1.1. Paragraph management
Adventuron allows for multiple ways to split text by paragraph. The first way is to write your location text on a single line and to separate using the following pattern of text '\n'.
For example:
0001_living_room : location "You are in a comfortable living room.\nYou hear the sound of the main road outside.";
Another way is to use the backslash notation to write paragraphs out by hand. Backslash notation requries that the first (non blank) letter after the '=' is a backslash '\' character.
0001_living_room : location { text = \ You are in a comfortable living room. You hear the sound of the main road outside. \ }
3.2. Navigation
There are multiple ways to define links between locations, but the easiest method is via the navigation section.
navigation { from[], direction[], to[]= { 0001_living_room, east, 0002_kitchen, 0001_living_room, west, 0003_hallway, } }
The block of code shown above will create 4 links. East from the living room to the kitchen, west from the kitchen to the living room, west from living room to the hallway and east from the hallway to the living room.
3.2.1. One Way Navigation
Sometimes you may require to create a one-way navigation connection. To achieve this, the '_oneway' suffix may be used. In this code snippet, there is no method for the player to return to the living room (or to anywhere) from the kitchen.
navigation { from[], direction[], to[]= { 0001_living_room, east_oneway, 0002_kitchen, } }
See the navigation section in the appendices for more options.
3.2.2. Conditional Navigation / Blocking
The navigation connections specified in this section relate to vanilla location to location mappings. An adventure can also move the player (or other characters/objects) around explicitly via intercepting user input. It may also block a player from travelling through a defining location to location mapping.
Location Blocks
################################## ## The start location ################################## start_location = passageway setup { ################################################ ## Run this subroutine at the start of the game ################################################ initialization_subroutine = init } ################################## ## All locations in adventure ################################## locations { throne_room : location "You are in the throneroom. The sacred wine is here."; passageway : location "You are in a long stone passageway."; } ################################## ## Navigation paths ################################## navigation { from[], direction[], to[]= { throne_room, south, passageway, } } ################################## ## The Game Logic ################################## code { t1_on_input[] { : match "kneel _" { : unblock "throne_room"; // Remove the block on the throne room : print "Such behaviour is worthy of a knight."; : press_any_key; : redescribe; } : match "drink wine" { : if (is_at "throne_room") { : stagger "You drink the sacred wine.\nYou are at peace once again.\nCongratulations, you have completed the game." ; : end_game ; } } } subroutines [] { #################################### ## Setup block at beginning of game #################################### init : subroutine { : block location="throne_room" description="A knight does not blunder into the sacred chamber without pause."; } } } look_and_feel { layout_order = H D O X }
3.3. Adding Objects
Objects are items in the game that can be manipulated. They will be listed at a location.
objects { candle : object "A wax candle"; coat : wearable "A dufflecoat"; flowers : scenery "An arrangement of flowers"; }
Adventuron understands the concept of wearing objects, and will automatically support 'wear' and 'remove' verbs for objects defined as wearable.
3.3.1. Object Ids
Objects Ids are significant by default. They must match the pattern [[ADJECTIVE]]_[[NOUN]]. When specified this way, the objects register adjectives and nouns implicitly in the vocabulary table.
Adjectives can generally be ignored and are used to disambiguate between two objects sharing the same noun (red key, green key).
3.3.2. Being Explicit
If you prefer ids being completely independent, and not used to imply vocabulary, then use the 'scan_entity_ids_for_vocab_items=false' config setting and manually associate objects with vocabulary words. At least one noun is required per object in this mode. Optionally, adjectives can also be provided.
setup { scan_entity_ids_for_vocab_items = false } tables { objects { coat : wearable "A brown dufflecoat" { nouns[] = coat, jacket, dufflecoat; adjectives[] = brown; } } }
or
setup { scan_entity_ids_for_vocab_items = false } tables { objects { coat : wearable "A brown dufflecoat" { nouns[] = coat; adjectives[] = brown; } } vocabulary { words[] { coat : noun / aliases [] = jacket, dufflecoat; } } }
The advantage of the second approach is that the same aliases can be reused by another coat in the game.
There is no requirement to create a vocabulary item for any adjectives or nouns used by objects. The vocabulary table is generally useful as a shared alias lookup table for words that may be used by one or more object or entity.
3.3.3. Object Start Location
If an object is created without a start locations, then it does not exist. Objects can start nowhere, with the player, or at a location. If the object starts with the player, then the location="inventory" should be used.
This will not collide with the id of a location called "inventory" because "inventory" is not permitted as a location name.
objects[] { // Will start inside the player's possessions coat : wearable "A dufflecoat" start_location="chapel"; }
objects[] { // Will start inside the player's possessions coat : wearable "A dufflecoat" start_location="inventory"; }
objects[] { // Will start inside the player's possessions and WORN coat : wearable "A dufflecoat" { start_location = inventory is_initially_worn = true } }
| We use a different syntax in the 3rd example. We do this purely for aesthetic reasons, so as not to place too much information onto a single line. See the Rion section for more information. |
3.4. Adding Game Logic
Game logic can be added by adding a 'code' block at the base of the root document.
code { // Game logic goes here }
The code section deals with:
-
Commands
-
Variables - Keeping Track of Game State (integers, booleans)
-
User Input Processing (T1)
-
Game Events (T2, T3, T4)
The game logic block allows custom logic to be tied into the game engine, and to respond to users text in a number of ways. A complex diagram is available, but here is a rough summary of the game loop.
-
User enters text.
-
Text is compared against expected text (T1 block), and if it matches, then the handler for that text block is executed.
-
A handler consists of a number of commands.
-
DONE, RETURN and REDESCRIBE are the three special handlers. Both DONE and REDESCRIBE will force a stop to evaluating any other conditions. RETURN will stop evaluating only for the current subroutine (only if within a subroutine).
-
When a room is described, the T2 block is executed.
-
After an input is submitted, the T3 block is executed. The T3 block may sometimes be skipped, if there was a REDESCRIBE in the T1 or T2 blocks (the redescribe would execute their own T3 block).
3.4.1. The T1 Table
Triggers are points during gameplay where user specified code is executed.
code { t1_on_input { : match "place ladder" { // Commands to execute } } }
3.4.2. Commands
Commands are instructions that should be performed. Adventuron uses a simple scripting language to be able to conditionally perform some work depending on if some conditions are satisfied.
Commands are usually subject to a trigger condition, and one or more conditions. Conditions are typically defined via boolean expressions.
When a command performs its work it is referred to as "execution".
See the commands section of the appendices for a full list of commands.
3.4.3. Variables
Variables are pieces of information which can be stored, referenced and modified.
Variables represent the state of your game. Variables have an initial value, which can then be modified during the game.
Adventuron supports three kinds of variables:
-
Textual (known as messages / strings)
-
Numeric (known as integers)
-
Yes or No values (known as booleans)
Booleans are useful for keeping track of if something has occurred or not. For example, in an adventure, the first time you meet a character, they might deliver a vital piece of the plot to the player. For example, they will tell you about a strange noise they heard on the moors at night. Once this information has been presented to the player, that dialog should not longer occur again.
A boolean could then be set up as follows:
booleans[] { has_been_told_about_noise : boolean "false" ; // False is the initial value }
The above snippet establishes that as the game starts, the player has NOT been told about the noise on the moors.
Boolean values are defined as 'true' and 'false'. These two values are standard across the vast majority of programming languages, and can be thought of as representing 'yes' (true) and 'no' (false) answers. Boolean variables can sometimes be referred to as 'flags'. A flag is something that is either in one of two states (off/on, up/down, true/false).
The name of the boolean variable is only important for the game designer. These variable names also help in debugging too. The variable could be named 'x' or 'y' but such names are not readable.
Getting back to our example, upon meeting a character for the first time, the following logic may execute (do not be concerned if you do not recognise the 'if' logic yet).
booleans { has_been_told_about_noise : boolean "false" ; // False is the initial value } code { t3_on_tick[] { : always { : if ((!has_been_told_about_noise) && is_object_present "policeman") { : print "Hello young sir, I was just about to come looking for you. I suppose you're here about the strange noises on the moor. You best talk to Mrs Harris up on the hill, she claims to have a recoding but she won't let anyone listen to it."; // Setting this to true here makes sure the policemen won't say this every time the player shares a location with him. : set_true "has_been_told_about_noise"; } } } }
Boolean variables can be referred to in any if statement in the game. All boolean variables are globally scoped.
| The boolean block also allows other types of booleans to be defined, such as constants, but these are not documented at this time. |
An integer is a whole number that does not have a fractional part.
Integer variables can be used to keep track of a count of items, or for storing the result of a calulation.
Integer variables can be defined within the integers block underneath the code block.
integers { hunger : integer "0" ; // 0 is the initial value }
Defining a message occurs at root level of the document (not within the code block).
strings[] { kings_message : message "I like toast" ; }
3.4.4. Conditional Commands (if statements)
If blocks can be used to conditionally execute commands. If an else command follows an if or an else_if commant, then the else block will be executed if the condition in the 'if' block returns a false / negative result.
In this snippet, by using the ':done;' command we flag that no more commands should be executed after encountering.
: match "examine altar" { : if (is_at "altar") { : print "A magnificent alter, there appears to be an inscription."; : done; } : else { : print "When you see one you'll examine it."; : done; } : print "This will not be printed because of the :done; commands"; }
3.4.5. Tutorial section
This is a work in progress, but please see the demo application:
########################################## ## Sample adventure .... ########################################## start_location = hallway ########################################## ## Introduction blub (optional) ########################################## story_info { intro_text = In this adventure you must drive to work. } ########################################## ## Locations ########################################## locations [] { drive : location "You are standing on your drive, your home lies to the south." graphic="car"; hallway : location "You are standing in your hallway. To the south is the driveway, to the west is your living room." header="Hallway" graphic="hallway"; kitchen : location "You are standing in a musky kitchen. The only exit is east, towards the living room."; living_room : location "You are standing in a modern lounge. The garden lies towards the north, the kitchen to the west, and the hallway to the east."; garden : location "You are in the garden, Bonnie's dog house lies to the north. Your living room stands to the south." graphic="garden"; dog_house : location "You are in the dog house." ; inside_car : location "You are in your car. You are so late for work!"; } ########################################## ## Navigation Paths ########################################## navigation / from[], direction[], to[] ={ garden, north, dog_house living_room, north, garden living_room, west, kitchen living_room, east, hallway hallway, south, drive inside_car, leave_oneway, drive } ########################################## ## Objects ########################################## objects[] { sausage : object "A juicy sausage" start_location = "kitchen" ; dog : object "Bonnie, the bonnie dog is here" start_location = "garden" ; car_keys : object "Some car keys" start_location ="dog_house"; car : scenery "Your car" conspicious="true" start_location ="drive"; unlocked_car : scenery "Your car" conspicious="true"; } ########################################## ## Vocabulary Aliasing ########################################## vocabulary { words[] { dog : noun { aliases [] = bonnie, doggy; } } } ########################################## ## Integer Variables ########################################## integers[] { dog_warn_buffer : integer "4" ; } #################################################################### ## Code Section #################################################################### code { #################################################################### ## User Input Pattern Matches #################################################################### t1_on_input [] { ############################################## ## Bonnie blocks the dog house ############################################## : match "n _" { : if (is_at "garden" && is_present"dog") { : warn "Bonnie looks at you and growls. You step back."; : pause "800"; : done; } } ############################################## ## Feeding Bonnie ############################################## : match "give sausage;feed dog" { : if (!(is_present "sausage" && is_present "dog")) { : warn "You're missing something !"; : done ; } : else { : gosub subroutine="feeddoggie"; } } : match "drop sausage" { : if (!(is_present "sausage" && is_present "dog")) { : drop; : done ; } : else { : gosub subroutine="feeddoggie"; } } ########################################### ## Can outsource matching to subroutines ########################################### : match "give _" { : print "Who to?"; : done; } : match "throw _" { : gosub subroutine="throw"; : done; } ########################################### ## Examinining stuff ########################################### : match "exam _" { : match "exam bonnie" { : if (is_present "dog" ) { : print "A golden haired doggie, she looks rather sad."; : done; } } : match "exam sausage" { : if (is_present "sausage" ) { : show_graphic "sausage"alignment ="left"; : print "A juicy pork sausage"; : done; } } } ########################################### ## Unlocking the car ########################################### : match "unlock car" { : if (is_present "car") { : if (is_present "car_keys") { :gosub subroutine="opencar"; } : else { : warn "With what?"; : done; } } } : match "enter car" { : if (is_present "car") { : if (is_present "car_keys") { : gosub subroutine="opencar"; } : else { : warn "It's locked."; } } : if (is_present "unlocked_car") { : goto "inside_car"; : redescribe; } } ########################################### ## Finishing the game ########################################### : match "drive work" { : if (is_at "inside_car") { : print "You have completed this mini adventure. Well done."; : end_game; } : else { : print "Once you are in your car, you can."; } } } #################################################################### ## Subroutines (can be referenced from event handlers) #################################################################### subroutines[] { opencar : subroutine { : pause "500"; : print "You unlock the car and enter"; : press_any_key; : swap o1="car" o2="unlocked_car"; : goto "inside_car"; : redescribe; } throw : subroutine { : match "throw leaf" { : print "leafy"; : return; } : print "It's not the thing you fling."; } feeddoggie : subroutine { : if (!is_present "dog") { : print "Nobody to feed it to"; } : else_if (is_present "dog" && is_present "sausage") { : print "Bonnie snatches the sausage from your hand and jumps up onto the roof to eat it."; : press_any_key; : destroy "dog"; : destroy "sausage"; : redescribe; } } } #################################################################### ## Per Tick Events #################################################################### t3_on_tick [] { : always { : if (is_present "dog") { : decrement "dog_warn_buffer"; } : if (dog_warn_buffer == 0 && chance "30" && is_present "dog") { : pause "150"; : print "Bonnie looks hungry"; } } } } #################################################################### ## How to style the adventure #################################################################### look_and_feel { derive_header_from_room_id = true list_object_style = list system_messages { you_cant_go_that_direction = There's nothing in that direction you like the look of } colors { paper = #000 negative_pen = #d33 } } #################################################################### ## Graphics #################################################################### assets / graphics[] { hallway : placeholder; car : placeholder; garden : placeholder; sausage : placeholder; }
3.4.6. Integer Expressions
Adventuron supports adding and subtracting numbers, both in terms of variable assignment as as part of a subexpression.
For example:
: if (1 < 0) { : print "This will never be printed"; } : if (1 < 0 + 2) { : print "This will be printed"; }
Addition, Subtraction, multiplication, division and modulo operators are supported.
All numeric expressions are integer based (all whole numbers, no fractions).
3.4.7. Boolean Expressions
Boolean expressions are used to describe logic that statement that is either true, or false.
Boolean expressions in Adventuron appear after 'if' and 'else_if' statements. They must resolve to a true or false answer.
Adventuron has a number of boolean functions, see the Boolean Functions section.
Boolean expressions are found between regular bracket characters "(" and ")".
: if (is_object_carried "saddle") { : print "The portal opens, ahead of you lies Ponytopia." ; : wait_any_user_input ; : end_game ; }
To apply more than one condition, we make use of boolean 'operators'. Using boolean operators is like constructing a sentence.
3.4.8. Boolean Operators
| Operator | Description |
|---|---|
bool1 || bool2 |
Represents a logical OR statement. |
bool1 && bool2 |
Represents a logical AND statement. |
! bool1 |
Represents a logical NOT statement. |
int1 == int2 |
Tests that two expressions return the same value. |
int1 != int2 |
Tests that two expressions do not return the same value. |
int1 <= int2 |
Tests that the first expression is less than or equal to the numeric value of the second expression |
int1 >= int2 |
Tests that the first expression is greater than or equal to the numeric value of the second expression |
int1 < int2 |
Tests that the first expression is less than the numeric value of the second expression |
int1 > int2 |
Tests that the first expression is greater than the numeric value of the second expression |
Or (||)
Represents a logical OR statement.
That is, it acts like the 'or' word in the english language. If one or more expressions evaluate to true, then the or expression evaluates to true.
| Or Expression | Result | Description |
|---|---|---|
false || false |
false |
If both expressions are false, then the result of the boolean OR operator is false. |
true || false |
true |
If one or more input expressions are true, then the result of the boolean OR operator is true. |
false || true |
true |
If one or more input expressions are true, then the result of the boolean OR operator is true. |
true || true |
true |
If both input expressions are true then the result of the boolean OR operator is true. |
In the following example, the player is granted access to Ponytopia only if they have the saddle OR the crown.
: if (is_object_carried "saddle" || is_object_carried "crown" ) { : print "The portal opens, ahead of you lies Ponytopia." ; : wait_any_user_input ; : end_game ; }
And (&&)
Represents a logical AND statement.
That is, it acts like the 'and' word in the english language. If all expresions in the and block evaluate to true, then the and itself expression evaluates to true.
| And Expression | Result | Description |
|---|---|---|
false && false |
false |
If both expressions are false, then the result of the boolean AND operator is false. |
true && false |
false |
If one or more input expressions are false, then the result of the boolean AND operator is false. |
false && true |
false |
If one or more input expressions are false, then the result of the boolean AND operator is false. |
true && true |
true |
If both input expressions are true then the result of the boolean AND operator is true. |
In the following example, the player is granted access to Ponytopia only if they have the saddle AND they are at the portal location.
: if (is_object_carried "saddle" && is_character_at "portal" ) { : print "The portal opens, ahead of you lies Ponytopia." ; : wait_any_user_input ; : end_game ; }
Not (!)
Represents a logical NOT statement. A supplied true value will resolve to false, and a supplied false value will evaluate to true. Flipping heck.
| Not Expression | Result | Description |
|---|---|---|
! false |
true |
If the input expression is false, then the result of a 'not' operator is true. |
! true |
false |
If the input expression is true, then the result of a 'not' operator is false. |
3.5. Vocabulary
The six word types supported are :
| Word Type | Description |
|---|---|
Verb |
Doing word, such as 'throw' or 'drink'. |
Noun |
Object or ubject, such as 'rope' or 'car' or 'man' or 'woman'. |
Adjective |
Describing word such as 'red', 'big', 'noisy'. |
Adverb |
Way of doing something, 'carefully', 'forcefully' |
Preposition |
A linking word, typically between two nouns, such as 'on', 'in', 'under' or 'beside' |
Word |
Special catch-all type that refers to a word that may be used in any context. This is provided for backwards compatibility with older game engines and should not be used for new games. |
Adventuron does not require that vocabulary is explicitly defined. If a word is referenced in the T1 block, or as an object id, then it is implicitly added to the dictionary in the appropriate category.
That said, defining explicit vocabulary is useful because Adventuron permits aliases to be defined for words.
It is not permitted for there to be overlaps in vocabulary ids within the same type of word category.
tables { vocabulary / words { throw : verb { aliases[] = chuck; } rock : noun { aliases[] = stone; } } }
| Explicit vocabulary items are not required if associating one or more adjectives and/or one or more nouns with a game object/entity. BUT, if supplied, it will explode the associations. |
3.5.1. N Char Parsing
Adventuron supports defining vocabulary in terms the first few characters of a word (such as the first 4 or 5 character). Typically you will never need to use this feature, but it can be useful if porting a game from an old file format, as earlier game engines stored vocabulary in terms of word prefixes in oder to deal with the memory constraints of earlier computing platforms.
To set up a 4 character parser, and vocabulary, use the following setting options. This will truncate all entered parsed words to 4 characters before comparing them to items in the vocabulary table.
setup { n_char_parser = 4 }
3.7. Adding Graphics
Graphics can be added by adding the following section to the base of the document. Graphics must be base64 encoded. Base64 encoding is a way of representing binary (such as graphical) data in text form.
assets { graphics { dog : base64_png "BASE 64 ENCODED PNG"; cat : base64_png "BASE 64 ENCODED PNG"; spoon_animated : base64_gif "BASE 64 ENCODED GIF"; } }
Graphics may be assigned to rooms as per following:
0002_kitchen : room "You are in a small yet well arranged kitchen." { graphic = kitchen }
The right hand side of the 'graphics = ' line must correspond to the id of an item in the graphics section. If it does not, the editor or compiler will complain.
3.7.1. Graphical Considerations
It is recommended that adventures attempt to keep graphics to less than 12 Kilobytes in size.
The recommended aspect ratio for banner images is between 2 and 2.4 horizontal pixels for every vertical pixel. 192x80 seems like a reasonable image size for retro style graphics. If drawing pictures of objects, or props, then 24x24 to 96x96 seems like a reasonable range.
It is recommended to choose a particular retro aesthetical and stick to it in terms of resolution and palette.
Small animated flourishes are possible with the use of animated gifs (flickering lamps, birds flying across sky). Do not attempt to inject full screen animations as base64 size would increase exponentially.
3.7.2. Placeholder graphics
Adventuron also supports placeholder graphics, for when an image is not yet ready. If the interpreter encounters a placeholder graphic entry, it will simply ignore it safely.
assets { graphics { bird : placeholder; house : placeholder; bedroom : placeholder; lobby : placeholder; } }
4. The Interpreter
The interpreter defined four types of 'tick', which is equivalent to a unit of time within the game world.
4.2. T1 Processing (Diagram T1)
The T1 tick processes logical sentences from the command line. This is approximately equivalent to the 'event' table in 'The Quill'. The T1 tick is where handling logical sentences usually takes place.
4.3. T2 Processing (Diagram T2)
The T2 tick is executed every time a location is re described (which may not be every game tick).
4.4. T3 Processing (Diagram T3)
The T3 tick is executed after the T1 tick has been processed and after the T2 handlers have been processed. This is approximately equivalent to the 'action' table in 'The Quill'. Note, the T3 tick does not execute if the location is explicitly redescribed (as this will be followed by a T3 tick of its own).
| The T3 handler will be skipped if the T1 or T2 tick issues a redescribe. |
4.5. T4 Processing (Diagram T4)
The T4 tick is executed after the T1 tick has been processed and after the T2 (and optionally T3) ticks have been processed. This is approximately equivalent to the 'action' table in 'The Quill'.
| The T4 tick will never be skipped even if the T1 or T2 tick issues a redescribe. |
5. The Adventuron Model
5.1. Adventure
Represents the telling of a text adventure or interactive fiction tale. Adventuron uses various tables to construct a story or game.
Typically a story/game is made up of one or more rooms which can be populated with one or more entities. The player/reader is able to make choices, move around the environment, and solve puzzles. The player traditionally interacts with the game via either via multiple choice or submitting a command to the came in the form of verb (adjective) noun or verb (adjective) noun preposition (adjective) noun.
| Name | Description | Type |
|---|---|---|
start_location |
Define the start location of the adventure / story. |
Reference (String) |
locations []{} |
Contains locations in the adventure. A location is a physical room, or situation, that will be explained to the player. |
Map (1 .. n) of location |
assets (optional) |
Additional game resources, such as graphics. |
Contained instance of assets |
code (optional) |
Define game logic here, such as variables, events, parser responses, etc. |
Contained instance of code |
look_and_feel (optional) |
Configure the look and feel of this adventure.If the user does not supply a value, then an instance of look_and_feel will be created (with all default values set accordingly). |
Contained instance of look_and_feel |
navigation (optional) |
Define the links between rooms. These links can be overridden in the code section. |
Contained instance of navigation |
setup (optional) |
Configures settings related to the game engine. |
Contained instance of setup |
story_info (optional) |
Information on the story, age rating, genre, game type, difficulty, authorship, license, etc.If the user does not supply a value, then an instance of story_info will be created (with all default values set accordingly). |
Contained instance of story_info |
vocabulary (optional) |
Deals with words and phrases that can be understood by the sentence parser. |
Contained instance of vocabulary |
booleans []{} (optional) |
A bank of booleans to be able to be referenced. |
Map (0 .. n) of types of referenceable boolean expression types |
integers []{} (optional) |
A bank of integers to be able to be referenced. |
Map (0 .. n) of types of referenceable integer expression types |
objects []{} (optional) |
Objects in the gameworld. These might be required to proceed somewhere else in the game. |
Map (0 .. n) of types of object types |
strings []{} (optional) |
A bank of strings to be able to be referenced. |
Map (0 .. n) of types of referenceable string expression types |
zones []{} (optional) |
A room collection is a reference to a set of rooms to be associated with each other. They could perhaps be used as a racetrack for creatures, or could perhaps be used as a subregion of a map where certain triggers occur. |
Map (0 .. n) of zone |
start_location = locations [] { }
-
\* This is the entry point of the adventure model. The root object is implicit.
5.2. Abs
Converts a negative (less than zero number) into a positive number, and leaves a zero number and positive numbers alone.
| Name | Description | Type |
|---|---|---|
<content> |
Converts a negative (less than zero number) into a positive number, and leaves a zero number and positive numbers alone. |
List (1) of types of integer functions |
my_abs : abs {( /* Expression goes here */ )}
Instantiable Within :
-
abs { .. }
-
add_integer { .. }
-
integer_dynamic { .. }
-
max { .. }
-
min { .. }
-
random / maximum
-
random / minimum
-
set_integer { .. }
5.3. Add Integer
Adds an integer value onto a variable
| Name | Description | Type |
|---|---|---|
var |
Reference to: integer_variable |
Reference (String) |
value (optional) |
A value to set |
Integer |
<content> (optional) |
The integer to add to the variable |
List (1 .. n) of types of integer functions |
Exactly 1 of the following fields is required : [expression, value] |
: add_integer {( /* Expression goes here */ )}
Instantiable Within :
-
if { .. }
-
else_if { .. }
-
else { .. }
-
always { .. }
-
match { .. }
-
subroutine { .. }
5.4. Adjective
A 'describing' word such as 'red', 'big', 'noisy'.
| Name | Description | Type |
|---|---|---|
aliases []= (optional) |
Aliases for the current word. Aliases are not permitted to contain special characters. |
Set of Strings (1 .. n) |
nid (optional) |
Assigned a numeric value to a vocabulary item. This is provided for backwards compatibility with older databases. |
Integer |
my_adjective : adjective { }
Instantiable Within :
-
vocabulary / words [] { .. }
5.5. Adjust Time
Moves time forward
| Name | Description | Type |
|---|---|---|
num_minutes |
The number of minutes to move time forward by or back by. Negative -5 moves time back 5 minutes, positive 65 moves time forward by 65 minutes. By default clock wraps around on a 24 hour basis so stories must fit in 24 hour timeframe. |
Integer |
: adjust_time num_minutes="..." ;
Instantiable Within :
-
if { .. }
-
else_if { .. }
-
else { .. }
-
always { .. }
-
match { .. }
-
subroutine { .. }
5.6. Adverb
A way of doing something, 'carefully', 'forcefully'
| Name | Description | Type |
|---|---|---|
aliases []= (optional) |
Aliases for the current word. Aliases are not permitted to contain special characters. |
Set of Strings (1 .. n) |
nid (optional) |
Assigned a numeric value to a vocabulary item. This is provided for backwards compatibility with older databases. |
Integer |
my_adverb : adverb { }
Instantiable Within :
-
vocabulary / words [] { .. }
5.7. Always
Always perform this action
| Name | Description | Type |
|---|---|---|
exec (optional) |
Reference to: subroutine |
Reference (String) |
<content> (optional) |
Always perform this action |
List (0 .. n) of types of commands |
Exactly 0 or 1 of the following fields is required : [exec, content] |
: always { }
Instantiable Within :
-
code / t2_on_redescribed [] { .. }
-
code / t3_on_tick [] { .. }
5.8. Ask Bool
Ask the player a yes or no answer.
| Name | Description | Type |
|---|---|---|
question |
The question to ask the player. |
String |
var |
The boolean variable in which to store the result. |
Reference (String) |
no_answer (optional) |
(Empty string is NOT valid here) |
String |
yes_answer (optional) |
(Empty string is NOT valid here) |
String |
: ask_bool { question = var = }
Instantiable Within :
-
if { .. }
-
else_if { .. }
-
else { .. }
-
always { .. }
-
match { .. }
-
subroutine { .. }
5.9. Ask Int
Ask the player to supply a number
| Name | Description | Type |
|---|---|---|
max |
The maximum acceptable number for the player to select |
Integer |
min |
The minimum acceptable number for the player to select |
Integer |
question |
The question to ask the player. |
String |
var |
The boolean variable in which to store the result. |
Reference (String) |
min ⇐ max |
: ask_int { max = min = question = var = }
Instantiable Within :
-
if { .. }
-
else_if { .. }
-
else { .. }
-
always { .. }
-
match { .. }
-
subroutine { .. }
5.10. Ask Quit
Ask player if they want to end game
: ask_quit ;
Instantiable Within :
-
if { .. }
-
else_if { .. }
-
else { .. }
-
always { .. }
-
match { .. }
-
subroutine { .. }
5.11. Assets
Additional game resources, such as graphics
| Name | Description | Type |
|---|---|---|
graphics []{} (optional) |
A bank of graphics that can be used by the adventure. It is recommended that the images are maximum of 240x120 pixels, and use a limited palette of colours in order to keep the adventure size down, and also to enforce a common retro look and feel. |
Map (0 .. n) of types of graphics |
my_assets : assets { }
Instantiable Within :
-
adventure / assets
5.12. Base64 Gif
Specify a base64 representation of a gif image that can be referenced from the rest of the adventure. Ideally gifs should be under 12 kilobytes of text each.
| Name | Description | Type |
|---|---|---|
base64 |
A base 64 representation of a GIF (or animated GIF) image. A 2:1 aspect ratio is recommended. For retro graphics, 240x120 is a good suggestion resolution. By default, scaling is of the pixelated style (no filtering). |
String |
alt (optional) |
A textual description of the image, to be displayed in place of the image on platforms where images are not supported, or possibly in the event of an IO failure. |
String |
my_base64_gif : base64_gif "..." ;
Instantiable Within :
-
assets / graphics [] { .. }
5.13. Base64 Png
Specify a base64 representation of a png image that can be referenced from the rest of the adventure. Ideally pngs should be under 12 kilobytes of text each.
| Name | Description | Type |
|---|---|---|
base64 |
A base 64 representation of a PNG image. A 2:1 aspect ratio is recommended. For retro graphics, 240x120 is a good suggestion resolution. By default, scaling is of the pixelated style (no filtering). |
String |
alt (optional) |
A textual description of the image, to be displayed in place of the image on platforms where images are not supported, or possibly in the event of an IO failure. |
String |
my_base64_png : base64_png "..." ;
Instantiable Within :
-
assets / graphics [] { .. }
5.14. Beep
Plays a trivial beep.
| Name | Description | Type |
|---|---|---|
millis |
Duration is in milliseconds |
Integer |
pitch |
The pitch of the note. 0 represents middle c (440hz). 12 represents one octave higher (A5. 880hz), -12 represents A3 (220hz). |
Integer |
: beep millis="..." pitch="..." ;
Instantiable Within :
-
if { .. }
-
else_if { .. }
-
else { .. }
-
always { .. }
-
match { .. }
-
subroutine { .. }
5.15. Block
Blocks a location so that every path into it from other locations are blocked. The location is still able to be scripted into.
| Name | Description | Type |
|---|---|---|
description |
The description of the block to accessing the room. |
String |
location |
The room or zone to be blocked by an obstacle. Be careful that you do not create a game-breaking block. |
Reference (String) |
remove_obvious_exit (optional) |
The game engine can highlight exits in a room. When blocking a room or zone, by default, we also remove the blocked region from obvious exit rendering. |
Boolean |
subroutine (optional) |
A subroutine to execute when the player triggers the block … |
Reference (String) |
: block "..." ;
Instantiable Within :
-
if { .. }
-
else_if { .. }
-
else { .. }
-
always { .. }
-
match { .. }
-
subroutine { .. }
5.16. Block Path
Blocks a path between two specific locations.
- NOTE
-
This block is unidirectional unless configured otherwise. Also note that unblocking a path will not unblock a room block either, that must be done seperately.
| Name | Description | Type |
|---|---|---|
description |
The description of the block to accessing the room. |
String |
from |
The location to be blocked by an obstacle. Be careful that you do not create a game-breaking block. |
Reference (String) |
to |
The location to be blocked by an obstacle. Be careful that you do not create a game-breaking block. |
Reference (String) |
remove_obvious_exit (optional) |
The game engine can highlight exits in a room. When blocking a path, by default, we also remove the blocked direction from obvious exit rendering. |
Boolean |
subroutine (optional) |
A subroutine to execute when the player triggers the block … |
Reference (String) |
: block_path { description = from = to = }
Instantiable Within :
-
if { .. }
-
else_if { .. }
-
else { .. }
-
always { .. }
-
match { .. }
-
subroutine { .. }
5.17. Boolean
A global variable that holds a boolean value. A boolean value is something that is either true or false.
If a default is not supplied, then will default to a false value.
| Name | Description | Type |
|---|---|---|
default (optional) |
The initial value of this boolean variable. If not supplied then will default to a 'false' value. |
Boolean |
my_boolean : boolean "..." ;
Instantiable Within :
-
adventure / booleans [] { .. }
5.18. Boolean Const
A fixed boolean (true or false) value that can be referenced elsewhere.
Constants have the ability to supply different values depending on game difficulty setting, such that it is possible to set up the game differently if wired up to the game setup subroutine.
| Name | Description | Type |
|---|---|---|
default |
The default value if no per-difficulty overrides are provided. |
Boolean |
when_easy (optional) |
Boolean |
|
when_hard (optional) |
Boolean |
|
when_medium (optional) |
Boolean |
|
when_super_easy (optional) |
If no values are provided for super easy then easy values will be used for super easy. |
Boolean |
when_super_hard (optional) |
If no value is provided for super hard, then hard values will be used for super hard. |
Boolean |
my_boolean_const : boolean_const "..." ;
Instantiable Within :
-
adventure / booleans [] { .. }
5.19. Boolean Dynamic
An expression that always returns a true or false value.
All items contained within this block are treated like items in an AND block., that is, unless all expressions return a true value, then the condition will return a false value.
Or, and, and not statements are available, so if you want an or expression, then wrap your expressons in an or expression.
| Name | Description | Type |
|---|---|---|
<content> (optional) |
All these conditions must be true for the if statement to be satisfied. Functionally similar to "AND" statement. If no items are contained in here, then we can assume a true result. |
List (0 .. n) of types of boolean functions |
my_boolean_dynamic : boolean_dynamic {( /* Expression goes here */ )}
Instantiable Within :
-
adventure / booleans [] { .. }
5.20. Chance
Will return true x percent of the time
| Name | Description | Type |
|---|---|---|
percentage |
Will return true x percent of the time |
Integer |
: chance "..." ;
Instantiable Within :
-
if ( .. )
-
else_if ( .. )
-
boolean_dynamic { .. }
-
set_boolean { .. }
5.21. Clear Screen
Clears the text on the screen
: clear_screen ;
Instantiable Within :
-
if { .. }
-
else_if { .. }
-
else { .. }
-
always { .. }
-
match { .. }
-
subroutine { .. }
5.22. Code
Define game logic here, such as variables, events, parser responses, etc.
| Name | Description | Type |
|---|---|---|
subroutines []{} (optional) |
Bundles of groups of commands that can be referenced from process tables. This allows common commands to be defined once then referenced multiple times. |
Map (0 .. n) of subroutine |
t1_on_input []{} (optional) |
For each logical sentence, this table is scanned in response to player input. |
List (0 .. n) of match |
t2_on_redescribed []{} (optional) |
Triggered after a room is described. If not changing a room or 'look’ing then this will not be triggered. |
List (0 .. n) of always |
t3_on_tick []{} (optional) |
Triggered after system actions, and movements. Executed after t2 where a room is describing itself, but sometimes t2 is not executed at all (where there has been an action that didn’t trigger a redescribe), in that case, t3 follows t1. |
List (0 .. n) of always |
my_code : code { }
Instantiable Within :
-
adventure / code
5.23. Colors
Specify default colors to use for different text displayed during the adventure. For example, you may wish to specify that the command line entry colour is different to the main text colour, or the inventory list is a different colour.
| Name | Description | Type |
|---|---|---|
darkroom_pen (optional) |
The default colour of text in a dark room. |
String |
exitlist_header_pen (optional) |
Colour corresponding to text such as "Exits:", some modes do not have a header and work exits into the paragraph text. |
String |
exitlist_link_pen (optional) |
The default direction link colour of the adventure. |
String |
exitlist_punctuation_pen (optional) |
The default colour of punctuation in exits section |
String |
inventory_header_pen (optional) |
Colour corresponding to text such as "In your bag you have:" when listing inventory / objects. |
String |
inventory_item_pen (optional) |
The default colour of the inventory items (overrides hyperlink). |
String |
negative_pen (optional) |
The colour of the parser responses (by default). If nothing is provided here, then the default colour of the style set (or client override) will be used. |
String |
paper (optional) |
The background colour of the panel containing the adventure. This is different to the background colour of the text of the adventure (which is usually transparent by default). |
String |
pen (optional) |
The default foreground colour of the text of the adventure. |
String |
prior_prompt_pen (optional) |
The default colour of the text that appears (optionally) above the command prompt. |
String |
prompt_pen (optional) |
The default colour of the command line prompt. |
String |
response_pen (optional) |
The colour of the parser responses (by default). Responses are text that is printed from event handlers (not room text). |
String |
textbox_pen (optional) |
The default colour of the command line text. |
String |
yousee_header_pen (optional) |
Colour corresponding to text such as "You See:" when listing items of interest in the current room. |
String |
yousee_item_pen (optional) |
The default colour of the listed items of interest in the current room. |
String |
my_colors : colors { }
Instantiable Within :
-
look_and_feel / colors
5.24. Confirm
Ask the player a yes or no answer. If the answer is negative, then the current command is cancelled.
| Name | Description | Type |
|---|---|---|
question |
The question to ask the player? |
String |
no_answer (optional) |
(Empty string is NOT valid here) |
String |
yes_answer (optional) |
(Empty string is NOT valid here) |
String |
: confirm question="..." ;
Instantiable Within :
-
if { .. }
-
else_if { .. }
-
else { .. }
-
always { .. }
-
match { .. }
-
subroutine { .. }
5.25. Create
Creates an object at a given room, zone, or character where to create the object (use 'player' or 'inventory' to create an object in the players inventory — note - weight limits will not be applied).
If no target is supplied then create object at current room.
| Name | Description | Type |
|---|---|---|
item_to_create |
Reference to: types of object types |
Reference (String) |
target (optional) |
The location, zone, or character where to create the object (use 'player' or 'inventory' to create an object in the players inventory — note - weight limits will not be applied). |
Reference (String) |
worn (optional) |
Will only be used if the reference refers to a character, and the object is wearable, otherwise ignored. |
Boolean |
: create "..." ;
Instantiable Within :
-
if { .. }
-
else_if { .. }
-
else { .. }
-
always { .. }
-
match { .. }
-
subroutine { .. }
5.26. Decrement
Decrements an integer variable
| Name | Description | Type |
|---|---|---|
var |
Reference to: integer_variable |
Reference (String) |
: decrement "..." ;
Instantiable Within :
-
if { .. }
-
else_if { .. }
-
else { .. }
-
always { .. }
-
match { .. }
-
subroutine { .. }
5.27. Delays
Describes the gameplay loop delays to use, so as to simulate slower platforms, or merely to give the player breathing space.
| Name | Description | Type |
|---|---|---|
default (optional) |
(in milliseconds) Default delay, for most categories. |
Integer |
parser (optional) |
(in milliseconds) This can be supplied to hint to simulate a slow parser. The player can override a parser delay. If no delay is provided then the default delay will be used. |
Integer |
press_any_key (optional) |
(in milliseconds) A delay to impose prior to running the the first T3 Action. If no delay is provided then the default delay will be used. |
Integer |
prompt_reappear_1 (optional) |
(in milliseconds) The delay to apply prior to the 'prior_prompt_text' appearing, this delay will occur whether the 'prior_prompt_text' is specified or not. This delay DOES NOT inherit the default delay. |
Integer |
prompt_reappear_2 (optional) |
(in milliseconds) The delay to apply after the 'prior_prompt_text' has appeared but before the prompt has appeared (delays the prompt appearing), this delay will occur whether the 'prior_prompt_text' is specified or not. This delay DOES NOT inherit the default delay. |
Integer |
stagger_initial (optional) |
(in milliseconds) This can be supplied to hint to simulate a slow parser. The player can override a parser delay. If no delay is provided then the default delay will be used. |
Integer |
my_delays : delays { }
Instantiable Within :
-
look_and_feel / delays
5.28. Destroy
Destroys an object (removes from a room or from inventory / worn status)
| Name | Description | Type |
|---|---|---|
entity |
Reference to: types of object types |
Reference (String) |
: destroy "..." ;
Instantiable Within :
-
if { .. }
-
else_if { .. }
-
else { .. }
-
always { .. }
-
match { .. }
-
subroutine { .. }
5.29. Distance To
Returns the number of moves required to travel to the zone or location in question.
| Name | Description | Type |
|---|---|---|
to |
The item or room or zone to find the distance towards … -1 if not accessible. By default this only uses the nagivation table and does not consider blocks. |
Reference (String) |
my_distance_to : distance_to "..." ;
Instantiable Within :
-
abs { .. }
-
add_integer { .. }
-
integer_dynamic { .. }
-
max { .. }
-
min { .. }
-
random / maximum
-
random / minimum
-
set_integer { .. }
5.30. Done
End processing of conditional action (exit the T table).
: done ;
Instantiable Within :
-
if { .. }
-
else_if { .. }
-
else { .. }
-
always { .. }
-
match { .. }
-
subroutine { .. }
5.31. Drop
Perform system drop command. This will be ignored if not executed from a T1 handler, or if the entity / object is not provided in the logical sentence. If no object is provided here, then used the noun1 associated with the object (if such an association exists).
| Name | Description | Type |
|---|---|---|
object (optional) |
If this is provided, then will try to perform action for the assigned object based on the verbs and nouns associated with the object (explicitly). If verbs and nouns are not explicitly associated with the object, then will look at adjective1 and noun1 in the logical sentence (if operating in T1 event handler). |
Reference (String) |
: drop "..." ;
Instantiable Within :
-
if { .. }
-
else_if { .. }
-
else { .. }
-
always { .. }
-
match { .. }
-
subroutine { .. }
5.32. Drop All
Drops all held items silently. No checks are performed (by default).
| Name | Description | Type |
|---|---|---|
mute_triggers (optional) |
Valid Values : [ true ] |
Enum |
: drop_all ;
Instantiable Within :
-
if { .. }
-
else_if { .. }
-
else { .. }
-
always { .. }
-
match { .. }
-
subroutine { .. }
5.33. Else
This block is executed only if the preceeding if and else_if blocks did not executed (their boolean expressions evaluated to a false result). An else block can only appear after an else_if or if block.
| Name | Description | Type |
|---|---|---|
<content> (optional) |
This block is executed only if the preceeding if and else_if blocks did not executed (their boolean expressions evaluated to a false result). An else block can only appear after an else_if or if block. |
List (0 .. n) of types of commands |
: else { }
Instantiable Within :
-
if { .. }
-
else_if { .. }
-
else { .. }
-
always { .. }
-
match { .. }
-
subroutine { .. }
5.34. Else If
Represents an optional block of code to be executed only if a conditional boolean expression returns a positive/true result. Can only follow an if statement or another else if statement.
| Name | Description | Type |
|---|---|---|
param_1 []{} |
All contained subexpressions must be true in order for this expression to return a true value. Functionally similar to "AND" statement. If no items are contained in here, then we can assume a true result. |
List (0 .. n) of types of boolean functions |
<content> (optional) |
Represents an optional block of code to be executed only if a conditional boolean expression returns a positive/true result. Can only follow an if statement or another else if statement. |
List (0 .. n) of types of commands |
: else_if ( /* expression here */ ) { /* Content goes here */ }
Instantiable Within :
-
if { .. }
-
else_if { .. }
-
else { .. }
-
always { .. }
-
match { .. }
-
subroutine { .. }
5.35. End Game
The game ends and a new game is offered.
: end_game ;
Instantiable Within :
-
if { .. }
-
else_if { .. }
-
else { .. }
-
always { .. }
-
match { .. }
-
subroutine { .. }
5.36. Flip
Flips the boolean value of a flag
| Name | Description | Type |
|---|---|---|
var |
Reference to: boolean_variable |
Reference (String) |
: flip var="..." ;
Instantiable Within :
-
if { .. }
-
else_if { .. }
-
else { .. }
-
always { .. }
-
match { .. }
-
subroutine { .. }
5.37. Format Time
Returns the current time formatted into a specified format. Format 1 is '07:52 PM', Type 2 is '19:52'.
| Name | Description | Type |
|---|---|---|
format_type (optional) |
Type 1 is '07:52 PM', Type 2 is '19:52' |
Integer |
: format_time format_type="..." ;
Instantiable Within :
-
print { .. }
-
set_string { .. }
-
stagger { .. }
-
string_dynamic { .. }
-
warn { .. }
5.38. Get
Perform system get command. This will be ignored if not executed from a T1 handler, or if the entity / object is not provided in the logical sentence. If no object is provided here, then used the noun1 associated with the object (if such an association exists).
| Name | Description | Type |
|---|---|---|
object (optional) |
If this is provided, then will try to perform action for the assigned object based on the verbs and nouns associated with the object (explicitly). If verbs and nouns are not explicitly associated with the object, then will look at adjective1 and noun1 in the logical sentence (if operating in T1 event handler). |
Reference (String) |
: get "..." ;
Instantiable Within :
-
if { .. }
-
else_if { .. }
-
else { .. }
-
always { .. }
-
match { .. }
-
subroutine { .. }
5.39. Gosub
Executes a subroutine (so that we can share command lists across multiple rooms).
| Name | Description | Type |
|---|---|---|
subroutine |
Reference to: subroutine |
Reference (String) |
: gosub "..." ;
Instantiable Within :
-
if { .. }
-
else_if { .. }
-
else { .. }
-
always { .. }
-
match { .. }
-
subroutine { .. }
5.40. Goto
If this command is executed, then all subsequent commands are ignored.
This command directs the player to the location specified. If the location specified is a location without a choice, then it is an ending. If the page specified is a good ending location, then the player has won the game. commands tied to the next location will be executed.
| Name | Description | Type |
|---|---|---|
location |
Reference to: location |
Reference (String) |
character (optional) |
The character to which the current command should apply. If this is not supplied, then we assume the player character. |
Reference (String) |
describe_new_room (optional) |
If operating in full adventure mode (not cyo adventure mode) then we can optionally move the player without informing them they have been moved |
Boolean |
fire_tick_event (optional) |
We can use this parameter to make sure that a tick isn’t executed when moving to a new room, therefore entry events are ignored. Only use this in full knowledge that the game can get into an unknown state (as the room will still be tagged as visited, so first visit events will never be executed when revisiting the new room). |
Boolean |
: goto "..." ;
Instantiable Within :
-
if { .. }
-
else_if { .. }
-
else { .. }
-
always { .. }
-
match { .. }
-
subroutine { .. }
5.41. If
Represents an optional block of code to be executed only if a conditional boolean expression returns a positive/true result.
| Name | Description | Type |
|---|---|---|
param_1 []{} |
All contained subexpressions must be true in order for this expression to return a true value. Functionally similar to "AND" statement. If no items are contained in here, then we can assume a true result. |
List (0 .. n) of types of boolean functions |
<content> (optional) |
Represents an optional block of code to be executed only if a conditional boolean expression returns a positive/true result. |
List (0 .. n) of types of commands |
: if ( /* expression here */ ) { /* Content goes here */ }
Instantiable Within :
-
if { .. }
-
else_if { .. }
-
else { .. }
-
always { .. }
-
match { .. }
-
subroutine { .. }
5.42. Increment
Increments an integer variable
| Name | Description | Type |
|---|---|---|
var |
Reference to: integer_variable |
Reference (String) |
: increment "..." ;
Instantiable Within :
-
if { .. }
-
else_if { .. }
-
else { .. }
-
always { .. }
-
match { .. }
-
subroutine { .. }
5.43. Integer
A global variable that holds an integer value
| Name | Description | Type |
|---|---|---|
default (optional) |
The default value |
Integer |
max_value (optional) |
If this is provided then the maximun value of an integer will never be above this value (inclusive) |
Integer |
min_value (optional) |
If this is provided then the minimun value of an integer will never be below this value (inclusive) |
Integer |
my_integer : integer "..." ;
Instantiable Within :
-
adventure / integers [] { .. }
5.44. Integer Const
A fixed integer value, that will never change.
Supports overrides for various difficulty profiles, which can then adjust the flow of the game (such as making battles easier, disabling harder puzzles, etc).
| Name | Description | Type |
|---|---|---|
default |
The default value to be used for this constant if no per-difficulty overrides are provided. |
Integer |
when_easy (optional) |
If no values are provided for super easy then medium values will be used for super easy. |
Integer |
when_hard (optional) |
If no value is provided for hard, then medium values will be used for hard. |
Integer |
when_medium (optional) |
If no value is provided for medium, then default value will be used for medium. |
Integer |
when_super_easy (optional) |
If no values are provided for super easy then easy values will be used for super easy. |
Integer |
when_super_hard (optional) |
If no value is provided for super hard, then hard values will be used for super hard. |
Integer |
my_integer_const : integer_const "..." ;
Instantiable Within :
-
adventure / integers [] { .. }
5.45. Integer Dynamic
Calculates a number using a series of calculation instructions. Can be referenced from other code chunks.
| Name | Description | Type |
|---|---|---|
<content> (optional) |
Adds up the result of the referenced numeric expression items. If no items are contained in here, then we can assume a zero. |
List (0 .. n) of types of integer functions |
my_integer_dynamic : integer_dynamic {( /* Expression goes here */ )}
Instantiable Within :
-
adventure / integers [] { .. }
5.46. Inventory
Perform system command inventory. This will be ignored if not executed from a T1 handler.
| Name | Description | Type |
|---|---|---|
for (optional) |
The location or entity for which to show the object contents. If this is not provided then the contents of the player’s inventory (worn and not worn) are listed). |
Reference (String) |
show_header (optional) |
If true, then prints the inventory header as setup via the system messages, e.g. "I have with me:" |
Boolean |
: inventory ;
Instantiable Within :
-
if { .. }
-
else_if { .. }
-
else { .. }
-
always { .. }
-
match { .. }
-
subroutine { .. }
5.47. Is At
Returns true if the player is at the location (or zone) specified
| Name | Description | Type |
|---|---|---|
location_or_zone |
Reference (String) |
|
character (optional) |
The character to which the current command should apply. If this is not supplied, then we assume the player character. |
Reference (String) |
: is_at "..." ;
Instantiable Within :
-
if ( .. )
-
else_if ( .. )
-
boolean_dynamic { .. }
-
set_boolean { .. }
5.48. Is Carried
Returns true if the player or identified character is carrying a specified object
| Name | Description | Type |
|---|---|---|
object |
Reference (String) |
|
character (optional) |
The character to which the current command should apply. If this is not supplied, then we assume the player character. |
Reference (String) |
: is_carried "..." ;
Instantiable Within :
-
if ( .. )
-
else_if ( .. )
-
boolean_dynamic { .. }
-
set_boolean { .. }
5.49. Is Debug Mode
Returns true if we are in debug mode. Be careful not to link game changing logic to this condition as you may end up with a scenario where something works in debug that does not work outside of debug mode.
: is_debug_mode ;
Instantiable Within :
-
if ( .. )
-
else_if ( .. )
-
boolean_dynamic { .. }
-
set_boolean { .. }
5.50. Is Exists
Returns true if the object/entity exists
| Name | Description | Type |
|---|---|---|
entity |
Reference to: types of object types |
Reference (String) |
: is_exists "..." ;
Instantiable Within :
-
if ( .. )
-
else_if ( .. )
-
boolean_dynamic { .. }
-
set_boolean { .. }
5.51. Is Object At
True if the object exists in a given room. Conceiled objects return false.
| Name | Description | Type |
|---|---|---|
location |
Reference (String) |
|
object |
Reference to: types of object types |
Reference (String) |
: is_object_at location="..." object="..." ;
Instantiable Within :
-
if ( .. )
-
else_if ( .. )
-
boolean_dynamic { .. }
-
set_boolean { .. }
5.52. Is Present
True if the object/entity exists in a given room or is part of the inventory (worn or unworn) and is not conceiled. If the object is conceiled then this will return false.
| Name | Description | Type |
|---|---|---|
entity |
The object/entity to test |
Reference (String) |
: is_present "..." ;
Instantiable Within :
-
if ( .. )
-
else_if ( .. )
-
boolean_dynamic { .. }
-
set_boolean { .. }
5.53. Is Worn
Returns true if the player or identified character is wearing the specified item
| Name | Description | Type |
|---|---|---|
object |
Reference (String) |
|
character (optional) |
The character to which the current command should apply. If this is not supplied, then we assume the player character. |
Reference (String) |
: is_worn "..." ;
Instantiable Within :
-
if ( .. )
-
else_if ( .. )
-
boolean_dynamic { .. }
-
set_boolean { .. }
5.54. Linefeed
Adds a paragraph seperator
: linefeed ;
Instantiable Within :
-
print { .. }
-
set_string { .. }
-
stagger { .. }
-
string_dynamic { .. }
-
warn { .. }
5.55. Load
Perform load command. This will be ignored if not executed from a T1 handler, or if the entity / object is not provided in the logical sentence.
: load ;
Instantiable Within :
-
if { .. }
-
else_if { .. }
-
else { .. }
-
always { .. }
-
match { .. }
-
subroutine { .. }
5.56. Location
A location in the adventure. If your location starts with three numbers and then an underscore character (such as 012_tent), anything after the underscore will not be shown to the player. Use this to help you remember each location option as you are writing the adventure.
| Name | Description | Type |
|---|---|---|
graphic (optional) |
Reference to a graphic resource to display before this room is described. |
Reference (String) |
header (optional) |
A single line header for this room or zone. If defined within a room, it overrides the zone description. A description header should be unique as it is used for mapping purposes. W emay drop the uniqueness requirement later if we introduce a mapping field override. |
String |
nid (optional) |
An optional numeric room identifier, can be used to numerically compare rooms, which is useful for conversions of games in older formats. Do not use unless you are an expert. |
Integer |
text (optional) |
The description of the location or situation |
String |
zones (optional) |
Reference(s) to: zone |
Set of References (0 .. n) |
Exactly 1 of the following fields is required : [text, text_dynamic] |
my_location : location { }
Instantiable Within :
-
adventure / locations [] { .. }
5.57. Look And Feel
Configure the look and the feel of the current adventure. Many settings that allow the adventure to have a feel of its own. These settings may be overridden by the client in most cases, but it is important for an adventure author to be able to define the tone of their adventure.
| Name | Description | Type |
|---|---|---|
default_room_graphic (optional) |
The graphic to display when there are no graphics to display in a room. |
Reference (String) |
derive_header_from_room_id (optional) |
If switched on then derive a header title from the room id (except the start room). |
Boolean |
enable_clear_screen (optional) |
Some adventures may wish to toggle off clearscreen behaviour. Adventuron got your back. |
Boolean |
font (optional) |
A look and feel style set. |
Enum |
font_size (optional) |
Font size for the given font for screens in landscape orientation. Each font will have font size gradients. If operating in hi-dpi mode, then the client is free to enter hi-dpi and essentially, everything will scale upwards from base values. |
Enum |
header_capitalization (optional) |
CONTROL THE CAPITALISATION OF ROOM HEADERS |
Enum |
header_enabled (optional) |
If true, then place a header above the gameplay panel that shows the short description for the current room / context, as well as the current score, if scores are supported. |
Boolean |
highlight_directions_in_text (optional) |
If set to true here, then directions are highlighted in the description of a location |
Enum |
intro_graphic (optional) |
A graphic to display at the beginning of the game… |
Reference (String) |
layout_order (optional) |
Define the layout order of items when a room is described. This uses a simple textual format for describing the vertical layout. |
String |
list_exits_style (optional) |
Describes how we should list exits when visiting a room. |
Enum |
list_object_style (optional) |
Describes how we should list objects when visiting a room. |
Enum |
max_width (optional) |
The maximum width of the screen in 'pixels' for screens in landscape orientation. As standard pixels are doubled in scale, so 320 virtual pixels is 320 doubled pixels. The additional resolution is still utilized by image scaling. If the client is in high-dpi mode, then a multiplier will be applied to this field. |
Enum |
object_list_capitalization (optional) |
Describes the capitalization policy for objects when they appear in lists. |
Enum |
panel_css (optional) |
NOTE: This may not be honoured by all clients. |
String |
prompt_graphic (optional) |
Provide a default graphic for the prompt |
Reference (String) |
room_description_capitalization (optional) |
CONTROLS THE CAPITALIZATION OF ROOM DESCRIPTIONS. |
Enum |
scanline_mode (optional) |
Specify the default scanline preferences for images added to the game. |
Enum |
show_prior_prompt_text (optional) |
If true, then shows the prior prompt text system message. |
Boolean |
string_capitalization (optional) |
CONTROLS THE CAPITALIZATION OF STRINGS (PRINT AND WARN). |
Enum |
textbox_allcaps (optional) |
Hint to capitalize user entry in the textbox. Some clients may not support this. |
Boolean |
wait_graphic (optional) |
A graphic to display when waiting for player input (for text based clients)… |
Reference (String) |
wait_graphic_alignment (optional) |
The alignment for the displayed graphic. |
Enum |
colors (optional) |
Specify default colors to use for different text displayed during the adventure. For example, you may wish to specify that the command line entry colour is different to the main text colour, or the inventory list is a different colour.If the user does not supply a value, then an instance of colors will be created (with all default values set accordingly). |
Contained instance of colors |
delays (optional) |
Describes the gameplay loop delays to use, so as to simulate slower platforms, or merely to give the player breathing space.If the user does not supply a value, then an instance of delays will be created (with all default values set accordingly). |
Contained instance of delays |
system_messages (optional) |
Override the system messages (such as the default message displayed picking up an object, dropping an object, not being able to go in a direction, not being able to understand the player).If the user does not supply a value, then an instance of system_messages will be created (with all default values set accordingly). |
Contained instance of system_messages |
separators []{} (optional) |
A bank of separators, to be references from a look and feel profile. |
Map (0 .. n) of separator |
my_look_and_feel : look_and_feel { }
Instantiable Within :
-
adventure / look_and_feel
5.58. Match
A pattern to match text. There are currently either 2 or 4 items that should be specified here.
The 2 item pattern is 'verb noun' or 'verb [entity_id]' or 'verb (adjective noun).
Special characters are '-' means, input should not include this word, '_' means can provide or not provide, and '*' means must provide. e.g. 'get \*' means match if verb is 'get' (or synonym) and if something is provided as verb or noun.
It should be noted that only words expliclty referenced as verb/nouns/adjectives or prepositions, or declared as such in the vocabulary section, will be detected by the parser as words in that category, otherwise they will be ignored.
- TODO
-
Document this some more
| Name | Description | Type |
|---|---|---|
pattern |
A pattern to match text. There are currently either 2 or 4 items that should be specified here. |
String |
exec (optional) |
Reference to: subroutine |
Reference (String) |
<content> (optional) |
A pattern to match text. There are currently either 2 or 4 items that should be specified here. |
List (0 .. n) of types of commands |
Exactly 0 or 1 of the following fields is required : [exec, content] |
: match { pattern = }
Instantiable Within :
-
if { .. }
-
else_if { .. }
-
else { .. }
-
always { .. }
-
code / t1_on_input [] { .. }
-
match { .. }
-
subroutine { .. }
5.59. Max
Returns the maximum of two or more numbers
| Name | Description | Type |
|---|---|---|
<content> |
Returns the maximum of two or more numbers |
List (2 .. n) of types of integer functions |
my_max : max {( /* Expression goes here */ )}
Instantiable Within :
-
abs { .. }
-
add_integer { .. }
-
integer_dynamic { .. }
-
max { .. }
-
min { .. }
-
random / maximum
-
random / minimum
-
set_integer { .. }
5.60. Min
Returns the minimum of two or more numbers
| Name | Description | Type |
|---|---|---|
<content> |
Returns the minimum of two or more numbers |
List (2 .. n) of types of integer functions |
my_min : min {( /* Expression goes here */ )}
Instantiable Within :
-
abs { .. }
-
add_integer { .. }
-
integer_dynamic { .. }
-
max { .. }
-
min { .. }
-
random / maximum
-
random / minimum
-
set_integer { .. }
5.61. Navigation
Define the links between rooms. These links can be overridden in the code section.
| Name | Description | Type |
|---|---|---|
direction []= |
A direction to link the 'to' and 'from' location together. The first item in the from list will correspond to the first item in the to lists and the first item in the directions table. All 3 tables must contain an identical amount of items. |
List of Strings (0 .. n) |
from |
The locations we wish to link from. The first item in the from list will correspond to the first item in the to lists and the first item in the directions table. All 3 tables must contain an identical amount of items. |
List of References (0 .. n) |
to |
The target locations. The first item in the from list will correspond to the first item in the to lists and the first item in the directions table. All 3 tables must contain an identical amount of items. |
List of References (0 .. n) |
my_navigation : navigation { direction [] = ; from [] = ; to [] = ; }
Instantiable Within :
-
adventure / navigation
5.62. Noun
In the sentence 'throw rope across valley', the noun would be 'rope' or its aliases.
| Name | Description | Type |
|---|---|---|
aliases []= (optional) |
Aliases for the current word. Aliases are not permitted to contain special characters. |
Set of Strings (1 .. n) |
nid (optional) |
Assigned a numeric value to a vocabulary item. This is provided for backwards compatibility with older databases. |
Integer |
proper (optional) |
If a noun is proper then it describes a person or a place. |
Boolean |
my_noun : noun { }
Instantiable Within :
-
vocabulary / words [] { .. }
5.63. Num Items Carried
Returns the number of items carried
my_num_items_carried : num_items_carried ;
Instantiable Within :
-
abs { .. }
-
add_integer { .. }
-
integer_dynamic { .. }
-
max { .. }
-
min { .. }
-
random / maximum
-
random / minimum
-
set_integer { .. }
5.64. Object
Describes an object that can be interacted with in the adventure, and is able to be added to the player inventory.
| Name | Description | Type |
|---|---|---|
text |
The name of the object (what appears). This name must be unique amongst all object names. |
String |
abstract (optional) |
If true, then this object is intended to be extended from, but is not intended to be used in the game. Currently not validating that we are not using abstract objects, just here as a documentation flag. In future, we may test to see that abstract objects are not used. |
Boolean |
adjectives []= (optional) |
An adverb to make the current entity more descriptive. |
Set of Strings (0 .. n) |
conspicious (optional) |
If an object is inconspicious, then it will not be listed as an object in the current room (but still present). Examining an object makes it conspicious, the text of a room or context of a room should enable the player to guess what to examine to bring the object to attention. |
Boolean |
container (optional) |
If true, then this object can be used to contain other objects. Bags, satchels, drawers. |
Boolean |
definate_article (optional) |
Usually 'the', used to specify a particular instance of a known object. |
String |
drop_messages (optional) |
A message to display when we successfully drop an object. |
String |
examine_message (optional) |
The examine mesage to display by default. If the 'on_examine' trigger is used, this message will be ignored. |
String |
indefinate_article (optional) |
Typically 'a' or 'an', AUTO mode makes best guess. |
String |
nouns []= (optional) |
A verb that can be used to identify this object via the pattern. The id of the object is not utilized by the pattern. If operating in pattern mode then this will be a mandatory field. |
Set of Strings (1 .. n) |
pick_up_messages (optional) |
A message to display when we successfully pick up an object. |
String |
start_location (optional) |
The location, zone, object, or character that the object is placed with. A blank entry or null represents an object that does not yet exist (may be created later). |
Reference (String) |
surface (optional) |
If true, then this object can be used to as a surface on which to place other objects. Tables, bench, rocks. |
Boolean |
weight (optional) |
The weight of an object. Defaults to '1'. Game defaults to the character being able to carry infinate items. |
Integer |
on_examine (optional) |
Commands to execute upon examining object. |
Contained instance of on_examine |
my_object : object { text = }
Instantiable Within :
-
adventure / objects [] { .. }
5.65. Ok
Shows 'ok' to player, or gives visual indication that something happened.
: ok ;
Instantiable Within :
-
if { .. }
-
else_if { .. }
-
else { .. }
-
always { .. }
-
match { .. }
-
subroutine { .. }
5.66. Parse Result
Performs a lookup from the last parsed logical sentence. This only make sense for handlers directly called from the T1 event routine, and return values are unspecified if called at other times.
| Name | Description | Type |
|---|---|---|
category |
Valid Values : [ verb, adjective1, noun1, matched_entity1, preposition, noun2, adjective2, matched_entity2, adverb ] |
Enum |
: parse_result "..." ;
Instantiable Within :
-
print { .. }
-
set_string { .. }
-
stagger { .. }
-
string_dynamic { .. }
-
warn { .. }
5.67. Pause
Pause the game for a number of milliseconds. The UI will not work whilst the game is paused by default, although the game engine may allow a pause to be interrupted by a keypress or other player input.
| Name | Description | Type |
|---|---|---|
millis |
The number of milliseconds to pause at normal game speed. If the player adjusts the speed of the game then this will be scaled accordingly. |
Integer |
: pause "..." ;
Instantiable Within :
-
if { .. }
-
else_if { .. }
-
else { .. }
-
always { .. }
-
match { .. }
-
subroutine { .. }
5.68. Placeholder
Specify a base64 representation of a gif image that can be referenced from the rest of the adventure. Ideally gifs should be under 12 kilobytes of text each.
| Name | Description | Type |
|---|---|---|
alt (optional) |
A textual description of the image, to be displayed in place of the image on platforms, possibly as a placeholder for an actual image, to be included later in the process. |
String |
my_placeholder : placeholder ;
Instantiable Within :
-
assets / graphics [] { .. }
5.69. Preposition
Words such as 'on', 'in', 'under' or 'beside'
| Name | Description | Type |
|---|---|---|
aliases []= (optional) |
Aliases for the current word. Aliases are not permitted to contain special characters. |
Set of Strings (1 .. n) |
nid (optional) |
Assigned a numeric value to a vocabulary item. This is provided for backwards compatibility with older databases. |
Integer |
my_preposition : preposition { }
Instantiable Within :
-
vocabulary / words [] { .. }
5.70. Press Any Key
Wait for some intercommand from the player before proceeding.
: press_any_key ;
Instantiable Within :
-
if { .. }
-
else_if { .. }
-
else { .. }
-
always { .. }
-
match { .. }
-
subroutine { .. }
5.71. Print
Show some response text to the player.
Printing can be in 3 forms. (1) Literal text
(2) Reference to a message
(3) An inline string expression.
The text will be split by newline character (\n) and shown in individual paragraphs.
The style of the message to be displayed can be overridden here, or will use the inherited default (from referenced message or from setup section).
| Name | Description | Type |
|---|---|---|
category (optional) |
Defines the type of this message, for use in styling. |
Enum |
print_mode (optional) |
If true then delay printed text output (does not apply to debug output). For every 32 characters, a 1 second delay will be inserted after the print statement. After the final paragraph, a "press any key" delay will be inserted. If this speed is too fast or slow, then it can be modified by the client. |
Enum |
ref (optional) |
The message to be shown. |
Reference (String) |
text (optional) |
Text to print to the screen. The text will be split on the newline character. |
String |
<content> (optional) |
String expressions that will evaluate to text to display to the player. |
List (1 .. n) of types of string functions |
Exactly 1 of the following fields is required : [content, text, ref] |
: print {( /* Expression goes here */ )}
Instantiable Within :
-
if { .. }
-
else_if { .. }
-
else { .. }
-
always { .. }
-
match { .. }
-
subroutine { .. }
5.72. Ramload
Performs Ramload Action, ramload will load silently if setup/system_action_success == true. Otherwise it will inform the user of the load but will not perform a game-tick. A failure to load will always inform the player.
: ramload ;
Instantiable Within :
-
if { .. }
-
else_if { .. }
-
else { .. }
-
always { .. }
-
match { .. }
-
subroutine { .. }
5.73. Ramsave
Performs Ramsave Action
: ramsave ;
Instantiable Within :
-
if { .. }
-
else_if { .. }
-
else { .. }
-
always { .. }
-
match { .. }
-
subroutine { .. }
5.74. Random
Generates a random number between the supplied max and min values. If the minimum value is supplied lower than the maximum number then an exception will be thrown at runtime.
| Name | Description | Type |
|---|---|---|
maximum |
The end range number of the random number function (this should be one million/1,000,000 or below) |
Contained instance of types of integer functions |
minimum (optional) |
The start range number of the random number function (this should be zero or above). If minimum is not specified, then zero is the the default minimum. |
Contained instance of types of integer functions |
my_random : random { maximum { } }
Instantiable Within :
-
abs { .. }
-
add_integer { .. }
-
integer_dynamic { .. }
-
max { .. }
-
min { .. }
-
random / maximum
-
random / minimum
-
set_integer { .. }
5.75. Rating Info
N/A
| Name | Description | Type |
|---|---|---|
may_be_scary (optional) |
Set this to true if the adventure is not scary. |
Boolean |
rated_for []= (optional) |
Valid Values : [ child, teen, adult ] |
Set of Strings (1 .. n) |
my_rating_info : rating_info { }
Instantiable Within :
-
story_info / rating_info
5.76. Redescribe
Redescribes the current room and triggers the post describe ticks.
: redescribe ;
Instantiable Within :
-
if { .. }
-
else_if { .. }
-
else { .. }
-
always { .. }
-
match { .. }
-
subroutine { .. }
5.77. Remove
Perform remove command. This will be ignored if not executed from a T1 handler, or if the entity / object is not provided in the logical sentence.
| Name | Description | Type |
|---|---|---|
object (optional) |
If this is provided, then will try to perform action for the assigned object based on the verbs and nouns associated with the object (explicitly). If verbs and nouns are not explicitly associated with the object, then will look at adjective1 and noun1 in the logical sentence (if operating in T1 event handler). |
Reference (String) |
: remove "..." ;
Instantiable Within :
-
if { .. }
-
else_if { .. }
-
else { .. }
-
always { .. }
-
match { .. }
-
subroutine { .. }
5.78. Return
Ends execution of a subroutine or command block, and resumes execution of tick logic or calling subroutine.
: return ;
Instantiable Within :
-
if { .. }
-
else_if { .. }
-
else { .. }
-
always { .. }
-
match { .. }
-
subroutine { .. }
5.79. Room As String
Returns the current room (for the player character by default) as a string.
: room_as_string ;
Instantiable Within :
-
print { .. }
-
set_string { .. }
-
stagger { .. }
-
string_dynamic { .. }
-
warn { .. }
5.80. Room Number
If current room (for the player) starts with numeric characters, then convert leading numeric characters into an integer. If the current room does not start with numbers, then '1000000001' (one billion and one) will be returned.
NOTE : If using this, it is generally a good idea to setup the adventure to set 'room_ids_must_start_with_integers=true' for the adventure.
my_room_number : room_number ;
Instantiable Within :
-
abs { .. }
-
add_integer { .. }
-
integer_dynamic { .. }
-
max { .. }
-
min { .. }
-
random / maximum
-
random / minimum
-
set_integer { .. }
5.81. Save
Perform save command. This will be ignored if not executed from a T1 handler, or if the entity / object is not provided in the logical sentence.
: save ;
Instantiable Within :
-
if { .. }
-
else_if { .. }
-
else { .. }
-
always { .. }
-
match { .. }
-
subroutine { .. }
5.82. Scenery
Describes an object/feature that can be interacted with but is fixed in place (cannot be picked up / dropped).
| Name | Description | Type |
|---|---|---|
text |
The name of the object (what appears). This name must be unique amongst all object names. |
String |
abstract (optional) |
If true, then this object is intended to be extended from, but is not intended to be used in the game. Currently not validating that we are not using abstract objects, just here as a documentation flag. In future, we may test to see that abstract objects are not used. |
Boolean |
adjectives []= (optional) |
An adverb to make the current entity more descriptive. |
Set of Strings (0 .. n) |
conspicious (optional) |
If an object is inconspicious, then it will not be listed as an object in the current room (but still present). Examining an object makes it conspicious, the text of a room or context of a room should enable the player to guess what to examine to bring the object to attention. |
Boolean |
container (optional) |
If true, then this object can be used to contain other objects. Bags, satchels, drawers. |
Boolean |
definate_article (optional) |
Usually 'the', used to specify a particular instance of a known object. |
String |
examine_message (optional) |
The examine mesage to display by default. If the 'on_examine' trigger is used, this message will be ignored. |
String |
indefinate_article (optional) |
Typically 'a' or 'an', AUTO mode makes best guess. |
String |
nouns []= (optional) |
A verb that can be used to identify this object via the pattern. The id of the object is not utilized by the pattern. If operating in pattern mode then this will be a mandatory field. |
Set of Strings (1 .. n) |
start_location (optional) |
The location, zone, object, or character that the object is placed with. A blank entry or null represents an object that does not yet exist (may be created later). |
Reference (String) |
surface (optional) |
If true, then this object can be used to as a surface on which to place other objects. Tables, bench, rocks. |
Boolean |
weight (optional) |
The weight of an object. Defaults to '1'. Game defaults to the character being able to carry infinate items. |
Integer |
on_examine (optional) |
Commands to execute upon examining object. |
Contained instance of on_examine |
my_scenery : scenery { text = }
Instantiable Within :
-
adventure / objects [] { .. }
5.83. Score
Perform score command. This will be ignored if not executed from a T1 handler.
: score ;
Instantiable Within :
-
if { .. }
-
else_if { .. }
-
else { .. }
-
always { .. }
-
match { .. }
-
subroutine { .. }
5.84. Separator
A seperator to be referenced from look and feel settings. This can be used to seperate between different sections as printed by the game.
| Name | Description | Type |
|---|---|---|
tile |
The tile to be repeated. |
Reference (String) |
my_separator : separator tile="..." ;
Instantiable Within :
-
look_and_feel / separators [] { .. }
5.85. Set Boolean
Sets a true or false value into a boolean variable.
| Name | Description | Type |
|---|---|---|
var |
The variable whose value it is that we wish to assign a new value. |
Reference (String) |
value (optional) |
A literal value to assign to the variable. This is mutually exclusive with the 'content' field. |
Boolean |
<content> (optional) |
A reference to a boolean expression, from which we will set the variable designated in the 'var' field. This field and the 'value' field cannot be provided at the same time. |
List (1) of types of boolean functions |
Exactly 1 of the following fields is required : [content, value] |
: set_boolean {( /* Expression goes here */ )}
Instantiable Within :
-
if { .. }
-
else_if { .. }
-
else { .. }
-
always { .. }
-
match { .. }
-
subroutine { .. }
5.86. Set False
Sets a boolean flag to 'false'
| Name | Description | Type |
|---|---|---|
value |
The variable we wish to set to a boolean 'false' value. |
Reference (String) |
: set_false "..." ;
Instantiable Within :
-
if { .. }
-
else_if { .. }
-
else { .. }
-
always { .. }
-
match { .. }
-
subroutine { .. }
5.87. Set Integer
Sets a number into an integer variable.
| Name | Description | Type |
|---|---|---|
var |
The variable we wish to set to a numeric/integer value. |
Reference (String) |
value (optional) |
A value to set |
Integer |
<content> (optional) |
An expression from which to set the integer value |
List (1) of types of integer functions |
Exactly 1 of the following fields is required : [expression, value] |
: set_integer {( /* Expression goes here */ )}
Instantiable Within :
-
if { .. }
-
else_if { .. }
-
else { .. }
-
always { .. }
-
match { .. }
-
subroutine { .. }
5.88. Set Simple String
Sets a explicit string value into a string variable.
| Name | Description | Type |
|---|---|---|
var |
Store a string in this variable. |
Reference (String) |
text (optional) |
The value to store in the variable. Empty strings are accepted. |
String |
: set_simple_string var="..." ;
Instantiable Within :
-
if { .. }
-
else_if { .. }
-
else { .. }
-
always { .. }
-
match { .. }
-
subroutine { .. }
5.89. Set String
Load a value into a string variable using a string expression.
| Name | Description | Type |
|---|---|---|
var |
Store a string in this variable. |
Reference (String) |
text (optional) |
Explicit text for the string variable (this is mutually exclusive with expression) |
String |
<content> (optional) |
An expression to use (this is mutually exclusive with text). |
List (1 .. n) of types of string functions |
Exactly 1 of the following fields is required : [text, expression] |
: set_string {( /* Expression goes here */ )}
Instantiable Within :
-
if { .. }
-
else_if { .. }
-
else { .. }
-
always { .. }
-
match { .. }
-
subroutine { .. }
5.90. Set True
Sets a boolean flag to 'true'
| Name | Description | Type |
|---|---|---|
value |
The variable that we wish to assign to a boolean 'true' value. |
Reference (String) |
: set_true "..." ;
Instantiable Within :
-
if { .. }
-
else_if { .. }
-
else { .. }
-
always { .. }
-
match { .. }
-
subroutine { .. }
5.91. Setup
Configure the game engine. Use this to toggle various features such as parser response time, parser type, appearance, etc. Some of these settings can be overridden by UI settings in a client.
| Name | Description | Type |
|---|---|---|
add_standard_vocab_set (optional) |
If true, then we add in vocabulary items and aliases for common directions and verbs. |
Boolean |
dark_expression (optional) |
If this is true, then we enter 'dark' mode which overrides the room description and hides object lists if appropriate. |
Reference (String) |
dark_message_override (optional) |
If this referenced message is non-blank, then override the default darkness message with the content of the text here, this has utmost priority over all over overrides. We can use this to simulate conditional darkness (using a message_smart). |
Reference (String) |
default_print_category (optional) |
The default print command category. Defaults to 'response'. |
Enum |
initialization_subroutine (optional) |
A subroutine that is executed prior to describing the first player room. This can set up objects, puzzles, and display some intro messages or questions for the player. |
Reference (String) |
inventory_weight_limit_var (optional) |
If the player is constrained by how much they can carry, then set a numeric limit of items that the player can carry. Simply inventory systems might set all objects to have a weight of 1, therefore the weight limit of 8 would allow the player to carry 10 items simultaniously. |
Reference (String) |
n_char_parser (optional) |
If this is supplied, then all words supplied by the player will be trimmed to the number of characters specified by this field. |
Integer |
parser_type (optional) |
Defines the parser features that we will use, and this can also have a bearing on which vocabulary words are reserved. In future, we may add language specific parsers here such as Spanish (which has different rules for detecting adjectives and nouns). |
Enum |
scan_entity_ids_for_vocab_items (optional) |
Objects ids are automatically parsed for nouns and adjectives (only when one or more nouns have not been explicitly set). |
Boolean |
score_total_variable (optional) |
The total score variable (this can be modified by difficulty or some other measure). This is not required. |
Reference (String) |
score_variable (optional) |
The score variable. This is optional, and will be displayed via the 'score' command. if supplied. If not supplied, then a message will be displayed to the player informing them there is no score in the game. |
Reference (String) |
silent_system_action_success (optional) |
If true, a system action that is performed successfully will not emit any feedback to the client, this type of thing can be specified at a granular level but this is a universal override. |
Boolean |
support_it_substitution (optional) |
If false, then switch off 'it' substitution in the parser and just treat 'it' like a regular word. |
Boolean |
systemcommand_wear (optional) |
If true, then we support standard system 'wear' and 'remove' commands without having to add t1 handlers. |
Boolean |
t1_direction_analysis (optional) |
If true, then examine the T1 conditional actions for verbs that represent directions AND that evaluate to true at the current point in time, and add this direction to the exits for the room. This required an additional T1 scan per tick but assists with true exit listing in some older database games. It does NOT perform a deep scan. |
Boolean |
t4_subroutine (optional) |
This subroutine is called AFTER a T3 tick is finished, even if the T3 ends with DONE. In programming terms, think of this like a finally block around the T3 statement that executes always no matter what the result. The number of items executed in this block is not considered downstream. |
Reference (String) |
weight_includes_contained_items (optional) |
If true, then contained objects (and objects within worn) objects contribute to weight carried. If not, then only contained objects will be not taken into account. |
Boolean |
weight_includes_worn_objects (optional) |
If true, then worn objects (and objects within worn) objects contribute to weight carried. If not, then only unworn objects will be taken into account. |
Boolean |
my_setup : setup { }
Instantiable Within :
-
adventure / setup
5.92. Show Graphic
Show an adhoc graphic
| Name | Description | Type |
|---|---|---|
graphic |
Reference to a graphic resource to display. By default the screen will not be cleared. |
Reference (String) |
alignment (optional) |
The alignment for the displayed graphic. |
Enum |
clear_screen (optional) |
Clear the screen before displaying the graphic. |
Boolean |
: show_graphic "..." ;
Instantiable Within :
-
if { .. }
-
else_if { .. }
-
else { .. }
-
always { .. }
-
match { .. }
-
subroutine { .. }
5.93. Show Separator
Shows a graphical seperator line.
| Name | Description | Type |
|---|---|---|
separator |
Reference to a seperator resource to display. By default the screen will not be cleared. |
Reference (String) |
: show_separator "..." ;
Instantiable Within :
-
if { .. }
-
else_if { .. }
-
else { .. }
-
always { .. }
-
match { .. }
-
subroutine { .. }
5.94. Stagger
Show some response text to the player.
Printing can be in 3 forms. (1) Literal text
(2) Reference to a message
(3) An inline string expression.
The text will be split by newline character (\n) and shown in individual paragraphs.
The style of the message to be displayed can be overridden here, or will use the inherited default (from referenced message or from setup section).
| Name | Description | Type |
|---|---|---|
ref (optional) |
The message to be shown. |
Reference (String) |
text (optional) |
Text to print to the screen. The text will be split on the newline character. |
String |
<content> (optional) |
String expressions that will evaluate to text to display to the player. |
List (1 .. n) of types of string functions |
Exactly 1 of the following fields is required : [content, text, ref] |
: stagger {( /* Expression goes here */ )}
Instantiable Within :
-
if { .. }
-
else_if { .. }
-
else { .. }
-
always { .. }
-
match { .. }
-
subroutine { .. }
5.95. Store Random In Var
Store a random value between 0 and 999 in a variable
| Name | Description | Type |
|---|---|---|
var |
The variable to store a number between 0 and 999 in. |
Reference (String) |
maximum (optional) |
Default : 999 |
Integer |
minimum (optional) |
Default : 0 |
Integer |
minimum ⇐ maximum |
: store_random_in_var var="..." ;
Instantiable Within :
-
if { .. }
-
else_if { .. }
-
else { .. }
-
always { .. }
-
match { .. }
-
subroutine { .. }
5.96. Story Info
Information on the story, age rating, genre, game type, difficulty, authorship, license, etc.
| Name | Description | Type |
|---|---|---|
authors []= (optional) |
Name of one or more authors of this game. Role can be included in brackets after name. |
List of Strings (1 .. n) |
copyright_message (optional) |
A copyright message (indepedent to license) |
String |
ending_text (optional) |
Optional ending text for a good ending of the game. |
String |
intro_text (optional) |
Optional introduction text. |
String |
language (optional) |
The language that this adventure is written in. Note that this will be constrained somewhat by the parser if languages have a different grammar syntax to English (the default). This is a narrative only field at present. |
String |
license_full (optional) |
Full license text purtaining to the adventure. |
String |
license_short (optional) |
Short description of the license of the current adventure. |
String |
long_synopsis (optional) |
A longer description of the story / content of the adventure. For use in indexes. Should be no longer than a paragraph and should not contain spoilers. |
String |
name (optional) |
The name of the game / story |
String |
short_synopsis (optional) |
A short description of the story / content of the adventure. For use in indexes. |
String |
tags []= (optional) |
Tags to help users discover adventures. Typically use camel case with no spaces for tags. |
Set of Strings (1 .. 8) |
year_of_creation (optional) |
Year that the adventure was created |
String |
rating_info (optional) |
Describe which age groups that the game is best suited towards.If the user does not supply a value, then an instance of rating_info will be created (with all default values set accordingly). |
Contained instance of rating_info |
my_story_info : story_info { }
Instantiable Within :
-
adventure / story_info
5.97. String
A flag representing a string. A string will always be non-null, and can contain an empty string.
| Name | Description | Type |
|---|---|---|
default (optional) |
The default value |
String |
my_string : string "..." ;
Instantiable Within :
-
adventure / strings [] { .. }
5.98. String Const
A static message to be referenced from elsewhere (const_string).
| Name | Description | Type |
|---|---|---|
default |
The default value when no per-difficulty overrides are provided. |
String |
when_easy (optional) |
If no values are provided for easy then medium values will be used for easy. |
String |
when_hard (optional) |
If no values are provided for hard then medium difficulty will be used for hard. |
String |
when_medium (optional) |
If no values are provided for medium then default value (value) will be used for medium. |
String |
when_super_easy (optional) |
If no values are provided for super easy then easy values will be used for super easy. |
String |
when_super_hard (optional) |
If no value is provided for super hard, then hard values will be used for super hard. |
String |
my_string_const : string_const { default = }
Instantiable Within :
-
adventure / strings [] { .. }
5.99. String Dynamic
Builds a string based on a series of string building commands. This can be referenced from other parts of the game.
| Name | Description | Type |
|---|---|---|
<content> |
Builds a string based on a series of string building commands. This can be referenced from other parts of the game. |
List (1 .. n) of types of string functions |
my_string_dynamic : string_dynamic {( /* Expression goes here */ )}
Instantiable Within :
-
adventure / strings [] { .. }
5.100. Subroutine
A subroutine is a block of game commands that can be referenced from elsewhere in the adventure (typically from T2 or T3 events). Subroutines can also invoke other subroutines so that functionality can be broken into smaller chunks.
| Name | Description | Type |
|---|---|---|
<content> (optional) |
A subroutine is a block of game commands that can be referenced from elsewhere in the adventure (typically from T2 or T3 events). Subroutines can also invoke other subroutines so that functionality can be broken into smaller chunks. |
List (0 .. n) of types of commands |
my_subroutine : subroutine { }
Instantiable Within :
-
code / subroutines [] { .. }
5.101. Swap
Swaps the position of two object.
| Name | Description | Type |
|---|---|---|
o1 |
Reference to: types of object types |
Reference (String) |
o2 |
Reference to: types of object types |
Reference (String) |
: swap o1="..." o2="..." ;
Instantiable Within :
-
if { .. }
-
else_if { .. }
-
else { .. }
-
always { .. }
-
match { .. }
-
subroutine { .. }
5.102. System Messages
Override the system messages (such as the default message displayed picking up an object, dropping an object, not being able to go in a direction, not being able to understand the player).
You can use the following patterns:
${command} will repeat the entire logical sentence.
${verb} will extract a verb from the user input.
${noun1} will extract the first noun.
TODO :: More will be supported in the future.
| Name | Description | Type |
|---|---|---|
ask_new_game (optional) |
(Empty string is NOT valid here) |
String |
ask_quit (optional) |
(Empty string is NOT valid here) |
String |
be_more_specific (optional) |
Text to display when you perfom an ambigious action. |
String |
cannot_carry_any_more (optional) |
(Empty string is NOT valid here) |
String |
cant_take (optional) |
(Empty string is NOT valid here) |
String |
concise_exit_list_header (optional) |
(Empty string is NOT valid here) |
String |
empty_inventory (optional) |
(Empty string is NOT valid here) |
String |
i_cant_do_that (optional) |
Text to display when you can’t do something |
String |
inventory_list_header (optional) |
(Empty string is NOT valid here) |
String |
inventory_list_header_verbose (optional) |
(Empty string is NOT valid here) |
String |
it_is_dark (optional) |
Text to display when you are in a dark room. |
String |
list_object_end_text (optional) |
Describes how we should end text, when listing objects in a single line mode. |
String |
list_object_final_separator (optional) |
Describes how we should separate listed objects, when listing objects in a single line mode. |
String |
list_object_separator (optional) |
Describes how we should separate listed objects, when listing objects in a single line mode. |
String |
must_remove_first (optional) |
(Empty string is NOT valid here) |
String |
not_carried (optional) |
(Empty string is NOT valid here) |
String |
not_present (optional) |
Text to display when something you know about is not around to interact with. |
String |
object_list_header (optional) |
The text to appear before the listing items of interest in a room (in concise mode). This is usually text such as "You See:" or "You Observe:". |
String |
object_list_header_verbose (optional) |
The text to appear before the listing items of interest in a room (in concise mode). This is usually text such as "You See:" or "You Observe:". |
String |
on_drop (optional) |
Text to display when you drop an object. |
String |
on_get (optional) |
Text to display when you take an object. |
String |
on_remove (optional) |
Text to display when you wear an object |
String |
on_wear (optional) |
Text to display when you wear an object |
String |
post_quit (optional) |
(Empty string is NOT valid here) |
String |
prior_prompt (optional) |
The text to appear before the prompt. If provided, this will be styled as per the prompt colour. The prompt then be the default prompt using the default text pen. |
String |
prior_prompt_expression (optional) |
Reference to a string expression or variable for text to appear before the prompt. This has priority over the prior_prompt text, but both may be provided at the same time. |
Reference (String) |
prompt (optional) |
The default prompt for the adventure. If nothing supplied here then '>' will be used. |
String |
prompt_expression (optional) |
Reference to a string expression or variable for text to as the prompt prefix. This has priority over the 'prompt' text, but both may be provided at the same time. This will only be used if the text is a non blank value. |
Reference (String) |
there_are_no_obvious_exits (optional) |
(Empty string is NOT valid here) |
String |
unknown_noun (optional) |
Text to display when the noun is not understood |
String |
unknown_verb (optional) |
Text to display when the noun is not understood |
String |
verbose_exit_list_additional_exits_are_located (optional) |
(Empty string is NOT valid here) |
String |
verbose_exit_list_from_here_you_can_go (optional) |
(Empty string is NOT valid here) |
String |
verbose_exit_list_last_sep (optional) |
(Empty string is NOT valid here) |
String |
verbose_exit_list_sep (optional) |
(Empty string is NOT valid here) |
String |
verbose_exit_list_to_the (optional) |
(Empty string is NOT valid here) |
String |
verbose_exit_list_you_can_also_go (optional) |
(Empty string is NOT valid here) |
String |
worn_suffix (optional) |
(Empty string is NOT valid here) |
String |
you_already_wear (optional) |
(Empty string is NOT valid here) |
String |
you_are_already_carrying (optional) |
(Empty string is NOT valid here) |
String |
you_cant_go_that_direction (optional) |
Text to display when the player attempts to go in a direction that is not available. |
String |
you_cant_wear (optional) |
(Empty string is NOT valid here) |
String |
you_dont_wear (optional) |
(Empty string is NOT valid here) |
String |
you_see_nothing_special (optional) |
Text to display when you see nothing special (via examine) |
String |
my_system_messages : system_messages { }
Instantiable Within :
-
look_and_feel / system_messages
5.103. Turns (1)
Returns the number of inputs entered by the player.
| This is the Game Turns version of Turns. |
my_turns : turns ;
Instantiable Within :
-
abs { .. }
-
add_integer { .. }
-
integer_dynamic { .. }
-
max { .. }
-
min { .. }
-
random / maximum
-
random / minimum
-
set_integer { .. }
5.104. Turns (2)
Perform system command turns. This will be ignored if not executed from a T1 handler.
| This is the System Command Turns version of Turns. |
: turns ;
Instantiable Within :
-
if { .. }
-
else_if { .. }
-
else { .. }
-
always { .. }
-
match { .. }
-
subroutine { .. }
5.105. Unblock
Unlocks a room, so that paths are now open into the room or zone. This is different to blocking a path. If a path block exists to this room from another room, then the path block is unaffected.
| Name | Description | Type |
|---|---|---|
location |
The room to be blocked by an obstacle. Be careful that you do not create a game-breaking block. |
Reference (String) |
: unblock "..." ;
Instantiable Within :
-
if { .. }
-
else_if { .. }
-
else { .. }
-
always { .. }
-
match { .. }
-
subroutine { .. }
5.106. Unblock Path
Will unblock a path between two specific locations.
| Name | Description | Type |
|---|---|---|
from |
The location to be blocked by an obstacle. Be careful that you do not create a game-breaking block. |
Reference (String) |
to |
The location to be blocked by an obstacle. Be careful that you do not create a game-breaking block. |
Reference (String) |
: unblock_path from="..." to="..." ;
Instantiable Within :
-
if { .. }
-
else_if { .. }
-
else { .. }
-
always { .. }
-
match { .. }
-
subroutine { .. }
5.107. Verb
In the sentence 'throw rope across valley', the verb would be 'throw' or its aliases.
| Name | Description | Type |
|---|---|---|
aliases []= (optional) |
Aliases for the current word. Aliases are not permitted to contain special characters. |
Set of Strings (1 .. n) |
nid (optional) |
Assigned a numeric value to a vocabulary item. This is provided for backwards compatibility with older databases. |
Integer |
my_verb : verb { }
Instantiable Within :
-
vocabulary / words [] { .. }
5.108. Vocabulary
N/A
| Name | Description | Type |
|---|---|---|
words []{} (optional) |
Map (0 .. n) of types of word types |
my_vocabulary : vocabulary { }
Instantiable Within :
-
adventure / vocabulary
5.109. Warn
Show some response text to the player in the style of a warning.
This should typically be used for a negative response such as "You can’t do that!".
Warnings can be in 3 forms. (1) Literal text
(2) Reference to a message
(3) An inline string expression.
The text will be split by newline character (\n) and shown in individual paragraphs.
| Name | Description | Type |
|---|---|---|
print_mode (optional) |
If true then delay printed text output (does not apply to debug output). For every 32 characters, a 1 second delay will be inserted after the print statement. After the final paragraph, a "press any key" delay will be inserted. If this speed is too fast or slow, then it can be modified by the client. |
Enum |
ref (optional) |
The message to be shown. |
Reference (String) |
text (optional) |
Text to print to the screen. The text will be split on the newline character. |
String |
<content> (optional) |
String expressions that will evaluate to text to display to the player. |
List (1 .. n) of types of string functions |
Exactly 1 of the following fields is required : [content, text, ref] |
: warn {( /* Expression goes here */ )}
Instantiable Within :
-
if { .. }
-
else_if { .. }
-
else { .. }
-
always { .. }
-
match { .. }
-
subroutine { .. }
5.110. Wear
Perform wear command. This will be ignored if not executed from a T1 handler, or if the entity / object is not provided in the logical sentence.
| Name | Description | Type |
|---|---|---|
object (optional) |
If this is provided, then will try to perform action for the assigned object based on the verbs and nouns associated with the object (explicitly). If verbs and nouns are not explicitly associated with the object, then will look at adjective1 and noun1 in the logical sentence (if operating in T1 event handler). |
Reference (String) |
: wear "..." ;
Instantiable Within :
-
if { .. }
-
else_if { .. }
-
else { .. }
-
always { .. }
-
match { .. }
-
subroutine { .. }
5.111. Wearable
N/A
| Name | Description | Type |
|---|---|---|
text |
The name of the object (what appears). This name must be unique amongst all object names. |
String |
abstract (optional) |
If true, then this object is intended to be extended from, but is not intended to be used in the game. Currently not validating that we are not using abstract objects, just here as a documentation flag. In future, we may test to see that abstract objects are not used. |
Boolean |
adjectives []= (optional) |
An adverb to make the current entity more descriptive. |
Set of Strings (0 .. n) |
conspicious (optional) |
If an object is inconspicious, then it will not be listed as an object in the current room (but still present). Examining an object makes it conspicious, the text of a room or context of a room should enable the player to guess what to examine to bring the object to attention. |
Boolean |
container (optional) |
If true, then this object can be used to contain other objects. Bags, satchels, drawers. |
Boolean |
definate_article (optional) |
Usually 'the', used to specify a particular instance of a known object. |
String |
drop_messages (optional) |
A message to display when we successfully drop an object. |
String |
examine_message (optional) |
The examine mesage to display by default. If the 'on_examine' trigger is used, this message will be ignored. |
String |
indefinate_article (optional) |
Typically 'a' or 'an', AUTO mode makes best guess. |
String |
initially_worn (optional) |
Only used if the object is placed with a character |
Boolean |
nouns []= (optional) |
A verb that can be used to identify this object via the pattern. The id of the object is not utilized by the pattern. If operating in pattern mode then this will be a mandatory field. |
Set of Strings (1 .. n) |
pick_up_messages (optional) |
A message to display when we successfully pick up an object. |
String |
start_location (optional) |
The location, zone, object, or character that the object is placed with. A blank entry or null represents an object that does not yet exist (may be created later). |
Reference (String) |
surface (optional) |
If true, then this object can be used to as a surface on which to place other objects. Tables, bench, rocks. |
Boolean |
weight (optional) |
The weight of an object. Defaults to '1'. Game defaults to the character being able to carry infinate items. |
Integer |
on_examine (optional) |
Commands to execute upon examining object. |
Contained instance of on_examine |
on_remove (optional) |
An event to trigger upon removing up a worn object (does not fire if the object is not held). |
Contained instance of on_remove |
on_wear (optional) |
An event to trigger upon wearing a held object (does not fire if the object is not held). |
Contained instance of on_wear |
my_wearable : wearable { text = }
Instantiable Within :
-
adventure / objects [] { .. }
5.112. Weight
Weighs a given item.
| Name | Description | Type |
|---|---|---|
object |
Reference to: types of object types |
Reference (String) |
cap (optional) |
If provided, then if the measured weight is above this number, then it is capped at this number. This should only ever be used for backwards compatibility with old databases. |
Integer |
true_weight (optional) |
True weight is the weight of the object AND all contained objects, recursively. If true weight is not selected, then only the nominal weight of this object will be calculated. |
Boolean |
my_weight : weight "..." ;
Instantiable Within :
-
abs { .. }
-
add_integer { .. }
-
integer_dynamic { .. }
-
max { .. }
-
min { .. }
-
random / maximum
-
random / minimum
-
set_integer { .. }
5.113. Weight Carry Limit
Returns the limit of weight of items that the player is permitted to carry.
my_weight_carry_limit : weight_carry_limit ;
Instantiable Within :
-
abs { .. }
-
add_integer { .. }
-
integer_dynamic { .. }
-
max { .. }
-
min { .. }
-
random / maximum
-
random / minimum
-
set_integer { .. }
5.114. Weight Items Carried
Returns the weight of items carried
| Name | Description | Type |
|---|---|---|
cap (optional) |
If provided, then if the measured weight is above this number, then it is capped at this number. This should only ever be used for backwards compatibility with old databases. |
Integer |
count_mode (optional) |
If provided, then this performs an object count rather than an object weight. That is, every item helf will add one instead of its weight. The true weight flag still controls recursion. |
Boolean |
true_weight (optional) |
True weight is the weight of the object AND all contained objects, recursively. If true weight is not selected, then only the nominal weight of this object will be calculated. |
Boolean |
my_weight_items_carried : weight_items_carried ;
Instantiable Within :
-
abs { .. }
-
add_integer { .. }
-
integer_dynamic { .. }
-
max { .. }
-
min { .. }
-
random / maximum
-
random / minimum
-
set_integer { .. }
5.115. Word
A word that has no classification (noun, verb, adjective, etc). If this word type is used, then entity based matching is not possible and interrogating of the logical sentence by word type is also not possible.
| Name | Description | Type |
|---|---|---|
aliases []= (optional) |
Aliases for the current word. Aliases are not permitted to contain special characters. |
Set of Strings (1 .. n) |
nid (optional) |
Assigned a numeric value to a vocabulary item. This is provided for backwards compatibility with older databases. |
Integer |
my_word : word { }
Instantiable Within :
-
vocabulary / words [] { .. }
5.116. Zone
A zone is a reference to a set of rooms to be associated with each other. They could perhaps be used as a racetrack for creatures, or could perhaps be used as a subregion of a map where certain triggers occur.
| Name | Description | Type |
|---|---|---|
locations |
Reference(s) to: location |
Set of References (0 .. n) |
desc (optional) |
The description of the current zone |
String |
header (optional) |
A single line header for this room or zone. If defined within a room, it overrides the zone description. A description header should be unique as it is used for mapping purposes. W emay drop the uniqueness requirement later if we introduce a mapping field override. |
String |
my_zone : zone { locations [] = ; }
Instantiable Within :
-
adventure / zones [] { .. }
5.117. Boolean Functions
An expression that returns a true or false value
| Type | Description |
|---|---|
chance |
Will return true x percent of the time [link] |
is_at |
Returns true if the player is at the location (or zone) specified [link] |
is_carried |
Returns true if the player or identified character is carrying a specified object [link] |
is_debug_mode |
Returns true if we are in debug mode. Be careful not to link game changing logic to this condition as you may end up with a scenario where something works in debug that does not work outside of debug mode. [link] |
is_exists |
Returns true if the object/entity exists [link] |
is_object_at |
True if the object exists in a given room. Conceiled objects return false. [link] |
is_present |
True if the object/entity exists in a given room or is part of the inventory (worn or unworn) and is not conceiled. If the object is conceiled then this will return false. [link] |
is_worn |
Returns true if the player or identified character is wearing the specified item [link] |
5.118. Commands
A command is a unit of work to be performed. Typically in response to an event or hook in the game, such as a player entering a new room, a character entering a new room, some input entered by the player, or some variable being modified.
| Type | Description |
|---|---|
add_integer |
Adds an integer value onto a variable [link] |
adjust_time |
Moves time forward [link] |
ask_bool |
Ask the player a yes or no answer. [link] |
ask_int |
Ask the player to supply a number [link] |
ask_quit |
Ask player if they want to end game [link] |
beep |
Plays a trivial beep. [link] |
block |
Blocks a location so that every path into it from other locations are blocked. The location is still able to be scripted into. [link] |
block_path |
Blocks a path between two specific locations. |
clear_screen |
Clears the text on the screen [link] |
confirm |
Ask the player a yes or no answer. If the answer is negative, then the current command is cancelled. [link] |
create |
Creates an object at a given room, zone, or character where to create the object (use 'player' or 'inventory' to create an object in the players inventory — note - weight limits will not be applied). |
decrement |
Decrements an integer variable [link] |
destroy |
Destroys an object (removes from a room or from inventory / worn status) [link] |
done |
End processing of conditional action (exit the T table). [link] |
drop |
Perform system drop command. This will be ignored if not executed from a T1 handler, or if the entity / object is not provided in the logical sentence. If no object is provided here, then used the noun1 associated with the object (if such an association exists). [link] |
drop_all |
Drops all held items silently. No checks are performed (by default). [link] |
else |
This block is executed only if the preceeding if and else_if blocks did not executed (their boolean expressions evaluated to a false result). An else block can only appear after an else_if or if block. [link] |
else_if |
Represents an optional block of code to be executed only if a conditional boolean expression returns a positive/true result. Can only follow an if statement or another else if statement. [link] |
end_game |
The game ends and a new game is offered. [link] |
flip |
Flips the boolean value of a flag [link] |
get |
Perform system get command. This will be ignored if not executed from a T1 handler, or if the entity / object is not provided in the logical sentence. If no object is provided here, then used the noun1 associated with the object (if such an association exists). [link] |
gosub |
Executes a subroutine (so that we can share command lists across multiple rooms). [link] |
goto |
If this command is executed, then all subsequent commands are ignored. |
if |
Represents an optional block of code to be executed only if a conditional boolean expression returns a positive/true result. [link] |
increment |
Increments an integer variable [link] |
inventory |
Perform system command inventory. This will be ignored if not executed from a T1 handler. [link] |
load |
Perform load command. This will be ignored if not executed from a T1 handler, or if the entity / object is not provided in the logical sentence. [link] |
match |
A pattern to match text. There are currently either 2 or 4 items that should be specified here. |
ok |
Shows 'ok' to player, or gives visual indication that something happened. [link] |
pause |
Pause the game for a number of milliseconds. The UI will not work whilst the game is paused by default, although the game engine may allow a pause to be interrupted by a keypress or other player input. [link] |
press_any_key |
Wait for some intercommand from the player before proceeding. [link] |
Show some response text to the player. |
|
ramload |
Performs Ramload Action, ramload will load silently if setup/system_action_success == true. Otherwise it will inform the user of the load but will not perform a game-tick. A failure to load will always inform the player. [link] |
ramsave |
Performs Ramsave Action [link] |
redescribe |
Redescribes the current room and triggers the post describe ticks. [link] |
remove |
Perform remove command. This will be ignored if not executed from a T1 handler, or if the entity / object is not provided in the logical sentence. [link] |
return |
Ends execution of a subroutine or command block, and resumes execution of tick logic or calling subroutine. [link] |
save |
Perform save command. This will be ignored if not executed from a T1 handler, or if the entity / object is not provided in the logical sentence. [link] |
score |
Perform score command. This will be ignored if not executed from a T1 handler. [link] |
set_boolean |
Sets a true or false value into a boolean variable. [link] |
set_false |
Sets a boolean flag to 'false' [link] |
set_integer |
Sets a number into an integer variable. [link] |
set_simple_string |
Sets a explicit string value into a string variable. [link] |
set_string |
Load a value into a string variable using a string expression. [link] |
set_true |
Sets a boolean flag to 'true' [link] |
show_graphic |
Show an adhoc graphic [link] |
show_separator |
Shows a graphical seperator line. [link] |
stagger |
Show some response text to the player. |
store_random_in_var |
Store a random value between 0 and 999 in a variable [link] |
swap |
Swaps the position of two object. [link] |
turns |
Perform system command turns. This will be ignored if not executed from a T1 handler. [link] |
unblock |
Unlocks a room, so that paths are now open into the room or zone. This is different to blocking a path. If a path block exists to this room from another room, then the path block is unaffected. [link] |
unblock_path |
Will unblock a path between two specific locations. [link] |
warn |
Show some response text to the player in the style of a warning. |
wear |
Perform wear command. This will be ignored if not executed from a T1 handler, or if the entity / object is not provided in the logical sentence. [link] |
5.119. Graphics
Items in this category are listed below.
| Type | Description |
|---|---|
base64_gif |
Specify a base64 representation of a gif image that can be referenced from the rest of the adventure. Ideally gifs should be under 12 kilobytes of text each. [link] |
base64_png |
Specify a base64 representation of a png image that can be referenced from the rest of the adventure. Ideally pngs should be under 12 kilobytes of text each. [link] |
placeholder |
Specify a base64 representation of a gif image that can be referenced from the rest of the adventure. Ideally gifs should be under 12 kilobytes of text each. [link] |
5.120. Integer Functions
An expression that returns an integer value
| Type | Description |
|---|---|
abs |
Converts a negative (less than zero number) into a positive number, and leaves a zero number and positive numbers alone. [link] |
distance_to |
Returns the number of moves required to travel to the zone or location in question. [link] |
max |
Returns the maximum of two or more numbers [link] |
min |
Returns the minimum of two or more numbers [link] |
num_items_carried |
Returns the number of items carried [link] |
random |
Generates a random number between the supplied max and min values. If the minimum value is supplied lower than the maximum number then an exception will be thrown at runtime. [link] |
room_number |
If current room (for the player) starts with numeric characters, then convert leading numeric characters into an integer. If the current room does not start with numbers, then '1000000001' (one billion and one) will be returned. |
turns |
Returns the number of inputs entered by the player. [link] |
weight |
Weighs a given item. [link] |
weight_carry_limit |
Returns the limit of weight of items that the player is permitted to carry. [link] |
weight_items_carried |
Returns the weight of items carried [link] |
5.121. Object Types
Types of 'object' in the game. Objects don’t necessarily have to be inanimate objects. Objects tend to be the basis of puzzles in traditional adventure games.
| Type | Description |
|---|---|
object |
Describes an object that can be interacted with in the adventure, and is able to be added to the player inventory. [link] |
scenery |
Describes an object/feature that can be interacted with but is fixed in place (cannot be picked up / dropped). [link] |
wearable |
N/A [link] |
5.122. Referenceable Boolean Expression Types
Items in this category are listed below.
| Type | Description |
|---|---|
boolean |
A global variable that holds a boolean value. A boolean value is something that is either true or false. |
boolean_const |
A fixed boolean (true or false) value that can be referenced elsewhere. |
boolean_dynamic |
An expression that always returns a true or false value. |
5.123. Referenceable Integer Expression Types
A variable (holding an integer) to be used in the game. Variables are referenced by id.
| Type | Description |
|---|---|
integer |
A global variable that holds an integer value [link] |
integer_const |
A fixed integer value, that will never change. |
integer_dynamic |
Calculates a number using a series of calculation instructions. Can be referenced from other code chunks. [link] |
5.124. Referenceable String Expression Types
Items in this category are listed below.
| Type | Description |
|---|---|
string |
A flag representing a string. A string will always be non-null, and can contain an empty string. [link] |
string_const |
A static message to be referenced from elsewhere (const_string). [link] |
string_dynamic |
Builds a string based on a series of string building commands. This can be referenced from other parts of the game. [link] |
5.125. String Functions
An expression that returns a textual value (including empty string)
| Type | Description |
|---|---|
format_time |
Returns the current time formatted into a specified format. Format 1 is '07:52 PM', Type 2 is '19:52'. [link] |
linefeed |
Adds a paragraph seperator [link] |
parse_result |
Performs a lookup from the last parsed logical sentence. This only make sense for handlers directly called from the T1 event routine, and return values are unspecified if called at other times. [link] |
room_as_string |
Returns the current room (for the player character by default) as a string. [link] |
5.126. Word Types
Items in this category are listed below.
| Type | Description |
|---|---|
adjective |
A 'describing' word such as 'red', 'big', 'noisy'. [link] |
adverb |
A way of doing something, 'carefully', 'forcefully' [link] |
noun |
In the sentence 'throw rope across valley', the noun would be 'rope' or its aliases. [link] |
preposition |
Words such as 'on', 'in', 'under' or 'beside' [link] |
verb |
In the sentence 'throw rope across valley', the verb would be 'throw' or its aliases. [link] |
word |
A word that has no classification (noun, verb, adjective, etc). If this word type is used, then entity based matching is not possible and interrogating of the logical sentence by word type is also not possible. [link] |
Appendices
6. Sample Code
6.1. A Simple Two Room Adventure
This adventure has no end condition. The 'east' navigation option represents an eastward connection from '0001_start_location' to '0002_barn' PLUS a westward connection from '0002_barn' to '0001_start_location'. For one way connections iuse the '_oneway' suffix (such as 'east_oneway').
start_location = 0001_start_location navigation { from[], direction[], to[]= { 0001_start_location, east, 0002_barn, } } locations [] { 0001_start_location : location "You are standing in a field."; 0002_barn : location "You stand outside a barn"; }
7. Recipes
7.1. Implementing Hunger
start_location = 0001_start_location locations [] { 0001_start_location : location "You are at the start"; 0002_finish : location "You are at the finish"; } navigation { from[], direction[], to[]= { 0001_start_location, east, 0002_finish, } } code { integers[] { hunger : integer "0" ; } t3_on_tick[] { : always { : increment "hunger" ; : if (hunger > 8) { : print "You died of starvation!" ; : wait_any_user_input ; : end_game ; } : else_if (hunger > 5) { : print "You are hungry! Better find some food." ; } } } }
8. Deep Dive
Please see TODO CHART for information on the event handling mechism of the interpreter.
8.1. 'done' and 'return'
In this example we dig into the world of 'done' and 'return'.
A 'return' will stop execution of the current block, but will not cease execution of the current T table.
A 'done' will stop execution of the current block and will ALSO stop evaluation of any other blocks in the T tables.
A 'redescribe' in a T1 block will stop execution of T2, T3 and T4 blocks, but will then redescribe the current location and call T2, T3, and T4 blocks from there.
start_location = 0001_start_location setup { t4_subroutine = "t4"; } locations [] { 0001_start_location : location "roomdesc"; } code { t1_on_input[] { : match "a b" { : print "t1-a" ; : press_any_key ; : redescribe ; : print "t1-b" ; : press_any_key ; } } t2_on_redescribed[] { : always { : print "t2-a" ; : return; : print "t2-b" ; } : always { : print "t2-c" ; : done; : print "t2-d" ; } : always { : print "t2-e" ; } } t3_on_tick[] { : always { : print "t3-a" ; : return; : print "t3-b" ; } : always { : print "t3-c" ; : done; : print "t3-d" ; } : always { : print "t3-e" ; } } subroutines[] { t4 : subroutine { : print "t4-a" ; : return; : print "t4-b" ; } } }
roomdesc t2-a t2-c t3-a t3-c t4-a
t1-a << Adventure waits for user input>> roomdesc t2-a t2-c t3-a t3-c t4-a
9. The Rion Object Notation Language
Adventuron utilizes a new object notation called Rion. Rion is not designed to replace JSON or YAML, but rather to provide a notation that is easy to visually scan.
The following rough guide is not exhaustive.
9.1. Implicit Document & Comments
# Empty Document
// Empty Document
9.2. Objects
In Rion a document contains an implicit root object. A blank document will be parsed into containing a single root object with no contents. Every valid item parsed within a document is added to the root document. Within the root object and within any object, an object can contain attributes, objects and collections. All items within an object must be identified.
id : type { // Some contents }
id : type ;
9.3. Attributes
some_key = some_value
some_key = "some_value" ;
some_key = \ This is my multi line attribute. \
-
NOTE : linefeeds are still present but not shown in visualisation
-
NOTE : Whitespace is significant in this form, but adventuron automatically deals with indentation whitespace so don’t worry about it.
days_of_week[] = monday, tuesday, "wednesday", thursday ;
This is a one dimensional array of values.
from[], direction[], to[] ={ loc0, south_oneway, loc1, loc0, east_oneway, loc4, loc1, north_oneway, loc0 }
This form allows multiple multi value attributes to be provided in the form of a table. The object notation enforces that the right amount of items be provided on each line (corresponding to the header).
10. Use of Screenshots
This document uses images from various adventures from 30 years ago. To the best of knowledge, none of the adventures are currently sold, and screenshots are provided under copyright fair-use clauses.
The same screenshot may be used more than once, but each game will only have a single screenshot. Adventuron is not affilliated or endorsed by the authors of these adventures. If you are the author or rights holder of any of these adventures and would like to see these screenshots removed.
11. Technology
Adventuron built using Java, the Rion object notation language, cross compiling to JavaScript is provided by the excellent GWT project.
The Adventuron editor utilizes the Ace Editor project.
11.1. Parser Ambiguity
Entities within the game (objects and characters) can be uniquely described using adjective and noun pairs. If referring to an entity in a location, and there are two or more objects that match the adjective noun pair, then the game asks the user to specify which object they are referring to (via the a multiple choice list of object descriptions - which may be identical or unique).
11.2. Quill Compatibility
It is the belief of the author that Adventuron represents a superset of (non-presentation-specific) functioality of "The Quill", and therefore it should be possible to port Quill games into Adventuron.
11.3. Conditional Actions
Conditional actions are actions that will typically execute dependent on a boolean expression being true. The condition is optional.
Adventuron adopts the same approach as GAC, Quill, PAW, and the August 1980 article in Practical Computer, written by Ken Reed. The basic approach is that a list of actions is stored inside a table (or quasi-table) format. Some actions have conditions attached. All items are looked at in each 'tick' until a 'DONE' or 'REDESCRIBE' action is executed. At this point the the interpreter stops scanning through the current tick table, and moves onto the next tick or returns control back to the player (depending on which tick is executing).
Adventuron builds on this approach and supports the concept of subroutines, which is similar to the concept of custom response tables in PAW.
12. Contact Information
Adventuron is copyright of Consoli Ltd, UK, all rights reserved.
For any enquiries, please contact Chris Ainsley at c.b.ainsley@gmail.com