Room File Structure

Each room must be defined in its own file. The name of the file (without the extension) determines the name of the room as referenced by the engine and by effects such as +GOTO. For example, a file named secret_room.room will be registered as a room called secret_room.

Room file names should not contain any special characters or spaces and must be unique across the game.

The general structure of a single room file is as follows:

@ENTER Required +EFFECT Effects to execute when entering the room @EXIT Optional +EFFECT Effects to execute when exiting the room >Choice 1 +EFFECT Invoked when inputting "Choice 1" >Choice 2 +EFFECT Invoked when inputting "Choice 2" Add more choices as required

The @ENTER tag is mandatory and should (aside from comments) be the first line in the room file. It indicates the start of the room's content. The @EXIT block is optional and can be used to define effects that occur when leaving the room. Room files do not necessarily need to include choices if the @ENTER event forwards the player to another room.

Upon reaching the end of a block, the engine will await input from the player. The player can then input their choice, which then triggers the corresponding choice. In case the input does not match any available choices, an "Unknown option" message will be displayed, and the engine will prompt the player to try again.

Using the +GOTO effect, the game can transition to another room file. In this case, the current room's @EXIT effect will be executed (if present), followed by the @ENTER block of the new room.

Comments can be written using the prefix // and can be placed anywhere in the file except in text blocks, where they will be interpreted as part of the text.

Example

//An example room file @ENTER +TEXT You enter a mysterious room. +TEXT There is a sturdy DOOR to the right and a dark PASSAGE to the left. +TEXT What will you do? >DOOR +TEXT You step towards the door. //A key is needed to proceed IF key == 1 +TEXT Turning the key, the door slowly gives way. +GOTO secret_room ELSE +TEXT The door is locked. You need a key. ENDIF >PASSAGE +TEXT You approach the passage cautiously. It is cold and damp. //Go to another room +GOTO dark_passage

Special Characters

The following characters have special meanings in room files when placed at the start of a line:

@ Denotes the start of a room event block (such as @ENTER or @EXIT).
+ Denotes an effect to be executed.
> Denotes the start of a choice block.
// Denotes a comment. Comments are not processed in any way and have no effect on the output.
IF Denotes the start of an IF block. Must be closed by an ENDIF or ELSE block.
ELSE Denotes the start of an ELSE block. Must be preceded by an IF block and closed by an ENDIF block.
ENDIF Denotes the end of an IF block.

Choices

Choices represent the different options a player can pick in a room. Each choice has its own effects and may forward the player to another room. If the player is not sent to another room, they will be prompted to make a choice again. Choices are case-insensitive and leading and trailing spaces are ignored, which means that "gold", "GOLD", and " Gold " all refer to the same choice.

>GOLD +TEXT You take the gold. A trap springs into action. The floor gives way beneath you! +GOTO dungeon >LEAVE +TEXT You leave the room without taking any gold. +GOTO outside >WAIT +TEXT You wait patiently. Nothing happens.

Anti-Choice

The Anti-Choice >! is a special type of choice that executes when the player performs an input that does not match any of the defined choices in the room file. The user's choice is stored in the string variable input, which contains the text of the last given input.

>RED +TEXT You choose the red pill. >BLUE +TEXT You choose the blue pill. >! +TEXT You choose neither the red pill nor the blue pill. +TEXT Instead, you choose <svar=input>.