DSL ~ DSL Grammar

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))