World file

YATAGE needs a world file in order to be able to run a game: it is a plaintext YAML-formatted file (*.yml) which is itself structured in a specific fashion.

This file contains everything that is needed in order to create a text adventure game, namely:

• Rooms, which defines the physical dimension of the world;

• Items, which defines objects that can be found along the way.

The following section details how this file must be structured, following the YAML format.

World structure

At the very least, the world file must contain:

• A version

• A name

• A starting room (start)

• At least one well-formed room in rooms referenced by start above

version

Type: integer	Required: yes	Allowed values: 1
Example: version: 1

Although not used yet (at least in the earliest releases of YATAGE), this attribute tells which version the world file has been written in.

It will allow to handle future – inevitable – breaking changes of the world file’s structure.

name

Type: string	Required: yes	Format: none
Example: name: My awesome game

This attribute should be a one-line string and should be a few words long. It may be your world’s name, your hero’s name, your game’s name, etc.

It is shown emphasized when running a game at the very beginning, or when using the intro action.

start

Type: string	Required: yes	Format: room reference
Example: start: Down the street rooms: Down the street: description: You're on the sidewalk.

This attribute is a reference to the starting room of the game, in other words the room where the player will start playing.

See also rooms.

rooms

Type: mapping	Required: yes	Format: string => room	Minimum count: 1
Example: start: Down the street rooms: Down the street: description: You're on the sidewalk.

This attribute holds all the world’s rooms definition. It is a mapping between rooms references (a string) and a room structure.

References must obviously be unique. References are used as the in-game rooms name unless the rooms’s name has been set. References are shown when the player enters a room, and when the player invokes the look action. At least one well-formed room must be defined and referenced by start.

See also Room.

description

Type: string	Required: no	Format: none
Example: description: A short example game.

This attribute may be a multiline string of any size describing this world, which may be used as an introduction to the game.

It is shown when running a game at the very beginning (or when using the intro action), just after author (if set) or otherwise just after name.

author

Type: string	Required: no	Format: none
Example: author: Maxime "Epoc" G. (https://epoc.fr/)

This attribute should be a single-line string containing any information about the author(s) of this world.

It is shown when running a game at the very beginning (or when using the intro action), just after name and before description (if set).

items

Type: mapping	Required: no	Format: string => item
Example: items: security card: look: It looks a lot like a credit card.

This attribute holds all the world’s items definition. It is a mapping between items references (a string) and an item structure.

References must obviously be unique. References are used as the in-game items name unless the item’s alias has been set. References should preferably be lowercase.

See also Item.