DSL ~ User Stories

What We Want DSL to Do

• It should be easy for a user with no knowledge of Chiventure whatsoever to quickly write a simple item or room in the DSL in 1-2 lines.
• Whereas WDL is human-readable, the new DSL should be both human-readable and human-writeable.
• In comparison to WDL, the DSL should have a relatively generous syntax and/or grammar.
• The DSL should be far less reliant than WDL on punctuation ("';.-,([{ etc) or indentation for the structure of its definitions.
• The DSL should feature a lot of default settings, to allow for quick and easy definitions of rooms or items, with default parameters left implicit.
• The DSL should allow easy deployment of common synonyms for actions.
• If possible, the DSL should allow users to declare any room or item anywhere in the file.
• The DSL should allow users to duplicate code from items or rooms using variables.

Prototype DSL

Simple Declarations

Declaring a Game

GAME START dining room END bedroom
   	intro: Welcome home! You just got back from a long day of work at Company X. You're exhausted, and think that it'd be best to just eat some dinner and go to bed. You're currently in your dining room, and dinner is on the table.
	end condition: dinner eaten

Declaring a Room

ROOM living room
	short: Kevin's living room.
	long: The room is sensibly decorated.
	connections: NORTH to dining room, EAST to bedroom, WEST to bathroom

Declarations with Default Parameters

Declaring an Item

Here an item is declared with its short parameter unspecified, which is handled by assigning it a default short description. The actions are defined readably:

ITEM door IN living room
	long: This door leads to your bedroom.
	actions: OPEN, KICK
		OPEN success: You open the door.
		OPEN fail: You can't open the door.
		KICK success: The door applauds your marvelous kick... and then breaks.
		KICK fail: You stub your toe. Loser!

Declaring a Room with Default Parameters

ROOM kitchen
	long: You see various eating utensils scattered everywhere.
	connections: WEST to dining room

Custom Actions, Synonyms, Ambiguously Placed Items

We can also override default descriptions, and add synonyms for actions. Here:

• DEVOUR works in place of EAT, and the resulting WDL file will reflect the two actions as having the same success and failure.
• The terms fail and failure used while specifying action results are also interchangeable, to make the language more fault-tolerant.
• The location of the item is not specified, so as a default it is placed in the room defined most recently (kitchen). This allows users to write rooms followed by a list of the items they possess, making the language more readable.

ITEM salad
	short: A green salad.
	long: A side salad. Nothing remarkably special about it.
   	actions: EAT = DEVOUR, ROLL AROUND IN, CRITICIZE
		EAT condition: fork is in inventory
		EAT success: You eat the salad. You feel quite satisfied.
		EAT fail: You cannot eat the salad.
		ROLL AROUND IN success: You roll around in the salad. You feel like a very big vegetable.
		ROLL AROUND IN failure: Alas, you cannot roll around in the salad.
		CRITICIZE success: You say 'This salad could use more lettuce.' You smile, because you know deep down you're right.
		CRITICIZE failure: Try as you might, you cannot find anything negative to say about this excellent salad.

Defining and Using Variables

Declaring a Variable

$fork = "
ITEM Fork IN {room}
    short: A fork.
    long: A fork. There's nothing remarkably special about it.
"

Using Variables (Simple)

$fork { room: kitchen }
    actions: TAKE
        TAKE success: You take the fork
        TAKE fail: You can't take the fork

$fork { room: kitchen }
    actions: OPEN
        OPEN success: You open the fork
        OPEN fail: You can't open the fork

Overriding Values From Variables

Here, the long description given with the object would take precedence over the long description declared with the fork variable.

$fork { room: kitchen }
    long: A fork. There is something remarkable about it.

For more information, see #861: User Stories (DSL)