DSL ~ DSL Grammar

Current Rules

Declaring a Thing (Game, Room, or Item)

For a GAME (one per file), where \n represents a newline character:

GAME START [room id 0] END [room id 1] \n

For example:

GAME START reg END mansueto

For a ROOM:

ROOM [room id] \n

For example:

ROOM reg

For an ITEM in a ROOM:

ITEM [item id] IN [room id] \n

For example:

ITEM doing honest work in college IN reg

If an ITEM is declared inside a room, the IN [room] is not required.

Giving a Thing Properties

All things have properties, which can be declared thusly:

[property]: "[value]"\n

For example:

ITEM doing honest work in college IN reg
             short: "A book."
long: "This is Doing Honest Work in College, baybee! It's the best book — nay, the only book — ever written!"

The parser supports both whitespace treatments, and any statement of [property]: "[value]" on one line.

Special Properties

Connections

Rooms have connections, which are properties declared concisely as follows:

connections: [DIRECTION] TO [room id]

A direction is NORTH, SOUTH, EAST, or WEST. For example:

connections: NORTH TO observatory

Connections can be easily listed:

connections: NORTH TO observatory, WEST to tennis courts

Actions

Items have actions, which are properties declared concisely as follows:

actions: [ACTIONS]

For example:

actions: OPEN

Like connections, actions can be easily listed:

actions: OPEN, CLOSE, JUMPON

Note that Chiventure does not support all actions out of the box. While you are free to declare an action named, for example, JUMPON, in a .dsl file, Chiventure may be unable to interpret it and segfault.

Action Properties

Actions are given their own properties:

actions: [ACTIONS]
   [action] [property]: "value"

For example:

actions: OPEN, CLOSE
    OPEN success: "You opened the book."
    OPEN fail: "You did not open the book."
    CLOSE success: "You closed the book."
    CLOSE fail: "You did not close the book."

Variables

DSL supports variables, which allows for easy repetition of common patterns throughout a potentially complex document.

Declaring a Variable

On a single line (supports escaped characters)

$var_name = "var_content"

For example:

$fork0 = "ITEM fork"

On multiple lines

$var_name = """
var_content
"""

For example:

$fork1 = """
ITEM fork
    short: "This is a fork"
"""

Variables need not be terminated on a new line.

Declaring custom fields

$var_name = """
var_content {custom_field_a}"""

For example:

$fork2 = """
ITEM {adjective} fork
    short: "This is a {adjective} fork"
"""

Custom fields can be repeated, and multiple different custom fields are possible in one statement:

$fork3 = """
ITEM {adjective} fork
    long desc: "This is a {adjective} fork. It used to belong to {former_owner}."
"""

Using a variable

All examples use the variables defined in the previous section.

Using a simple variable

Simply include the variable name, and it will evaluate to the variable's prescribed contents:

$fork0 will evaluate to ITEM fork.

$fork1 will evaluate to

ITEM fork
    short: "This is a fork"

Using custom fields

Specify the contents of a variable's custom fields by including it in the curly braces after the variable is defined:

$var_name {custom_field: "custom value", ...}

For example, $fork2 {adjective: "red"} will evaluate to

ITEM red fork
    short: "This is a red fork"

...and $fork3 {adjective: "yellow", former_owner:"my grandma"} will evaluate to

ITEM yellow fork
    long desc: "This is a yellow fork. It used to belong to my grandma."

Defaults

The DSL parser will automatically (and sometimes, poorly) fill in default properties that are not included for games, rooms, and items as follows:

Games

Required

• start
• end

Optional

• intro

Rooms

Required

• id
• connections (required by Chiventure, not parser)

Optional

• short desc
• long desc

Items

Required

• id
• Location, defined either explicitly or implicitly

Optional

• short desc
• long desc
• Action properties, if actions are included