DSL ~ DSL Grammar - uchicago-cs/chiventure GitHub Wiki

Current Rules

Declaring a Thing (Game, Room, Player Class, NPC, 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.

For a `PLAYER_CLASS`

PLAYER_CLASS [player id] \n

For example:

  PLAYER_CLASS STUDENT

For a `NPC` in a `ROOM`

NPC [npc id] IN [room id] \n

For example,

NPC JACK IN classroom

Note: NPC declarations may or may not include a ROOM. With the current state of Chiventure, we cannot declare an NPC as an object directly in a ROOM declaration, so it is advised to declare the ROOM of the NPC in the NPC's declaration.

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."

Player Class Special Properties

`ATTRIBUTES`

Attributes of a PLAYER_CLASS are characteristics of that class. ATTRIBUTES will be declared on a new line. Then the attributes of the class will be listed below, each separated by a new line. ATTRIBUTES are depicted by two phrases, the former phrase being up to the game developer and the latter phrase being either TRUE or FALSE.

A visual depiction is shown below,

  PLAYER_CLASS [player class id]
      ...
      ATTRIBUTES
          [attribute name/phrase 1] TRUE
          [attribute name/phrase 1] FALSE
          [attribute name/phrase 1] TRUE

`BASESTATS`

BASESTATS of a player class involve the initial stats that player would have in the game. Common examples of stats might be health, mana, or magic, though the name of the stat is completely up to the game developer's choosing. After declaring BASESTATS, on a new line the developer would indicate the state name (i.e. health). After this, the next two lines will depict the CURRENT or initial status of that stat (a number) and the MAX possible status (a number). A visual depiction is listed below:

  PLAYER_CLASS [player class id]
      ...
      BASESTATS
          [stat name]
              CURRENT [integer]
              MAX [integer]

Full Example of a Player CLass

For further clarification, here is an example of what a PLAYER_CLASS might look like in a DSL file.

 PLAYER_CLASS STUDENT
      short desc: "This is a student."
      long desc: "His goal is to get an A in Professor Borja’s class."
      ATTRIBUTES
          studious TRUE
          procrastinator FALSE
          inquisitive TRUE
      BASESTATS
          grade
              CURRENT 80
              MAX 100

NPC Special Properties

`age` and `gender`

These are treated as normal properties the same as short desc and long desc. These are included here to avoid confusion in case one is looking at the DSL file thinking they may be special properties limited to NPCs.

`INVENTORY`

The inventory is an optional special property in NPC declarations. It is declared by writing INVENTORY on a new line. The INVENTORY contains a list of normal properties on its subsequent lines. This means an INVENTORY can have a short desc and a long desc. An INVENTORY is most likely to include item ids as its subsequent properties. The DSL does not currently support declaring full ITEM's solely in the INVENTORY.

A visual depiction is shown below:

  NPC [npc id] IN [room id]
      ...
      INVENTORY
          item_id: "[item id string]"
          item_id: "[item id string]"
          item_id: "[item id string]"
          item_id: "[item id string]"

`DIALOGUE`

Dialogue for an NPC is currently represented as a graph with nodes and edges. Each node contains the NPC dialogue option, and edges are indicated by what the player chooses to respond.

The current grammar has been implemented for DIALOGUE but it has not been tested.

A visual depiction is provided below:

  NPC [npc id] IN [room id]
      ...
      DIALOGUE
          NODE [node id] EDGE [edge id] TO [edge id]
                 [edge phrase] : "string"
                 [node pharse] : "string"

Current Tested Example of `NPC`

  NPC PROFESSOR IN computer lab
      short desc: "This is Professor."
      long desc: "This is the amazing professor who teaches CMSC 22000."
      age: "23"
      gender: "Male"
      INVENTORY
          item_id: "CPU"
          item_id: "Shirt Designer"
          item_id: "Glasses"
          item_id: "Power Point"

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

Player Classes

Required

id

Optional

short desc
long desc
ATTRIBUTES
BASESTATS

NPCs

Required

id
Location, defined either explicitly or implicitly

Optional

short desc
long desc
age
gender
INVENTORY (and any item_ids inside it)
DIALGOUE (and any dialogue options (nodes and edges))

DSL ~ DSL Grammar - uchicago-cs/chiventure GitHub Wiki

Current Rules

Declaring a Thing (Game, Room, Player Class, NPC, or Item)

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

For a ROOM:

For an ITEM in a ROOM:

For a PLAYER_CLASS

For a NPC in a ROOM

Giving a Thing Properties

All things have properties, which can be declared thusly:

Special Properties

Connections

Actions

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

Player Class Special Properties

ATTRIBUTES

BASESTATS

Full Example of a Player CLass

NPC Special Properties

age and gender

INVENTORY

DIALOGUE

Current Tested Example of NPC

Variables

Declaring a Variable

On a single line (supports escaped characters)

On multiple lines

Declaring custom fields

Using a variable

Using a simple variable

Using custom fields

Defaults

Games

Required

Optional

Rooms

Required

Optional

Items

Required

Optional

Player Classes

Required

Optional

NPCs

Required

Optional

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

For a `ROOM`:

For an `ITEM` in a `ROOM`:

For a `PLAYER_CLASS`

For a `NPC` in a `ROOM`

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.

`ATTRIBUTES`

`BASESTATS`

`age` and `gender`

`INVENTORY`

`DIALOGUE`

Current Tested Example of `NPC`