===================
HERITAGE statements
===================

action
------

Syntax::

  action(name):
      succeed:

Example::

  action(open_door):
      succeed: You open the door
      fail: You don't have a key
      require_inventory: key

action allows the developer to create specific commands that are not tied to a 
specific item and can always be executed (this specific example is better used 
as an on_open substatement on a door item).

name is the command the user will type. If it is more than one word, it should 
be seperated by an underscore.

action supports the following substatements::

  succeed: statement to print when the action succeeds
  fail: statement to print when the action fails
  require_location: locationnumber(X.Y.Z.) followed by a comma-seperated list of items that should be in that location
  require_here: comma-seperated list of items that should be on the player's current location
  require_inventory: comma-seperated list of items that should be in the player's inventory
  equals: check if variable is equal to value (variable, value)
  less_than: check if variable is less than a certain value (variable, value)
  more_than: check if variable is more than a certain value (variable, value)
  lose: comma-seperated list of items in inventory to disappear
  gain: comma-seperated list of items to be added to the inventory
  drop: comma-seperated list of items to be moved from the inventory to the current room

exit
----

Syntax::

  exit(id):

Example::

  exit(1):
      fail: The door is locked
      require_inventory: key

exit allows the developer to create special exits. These are exits that do not 
use a standard direction (north, east, south, west, northeast, southeast, 
northwest, southwest, up and down) or exits on a standard direction that have 
special requirements. id is an unique number. The same id should not be 
re-used for multiple exits.

exit supports the following substatements::

  succeed: statement to print when the action succeeds
  fail: statement to print when the action fails
  require_location: locationnumber(X.Y.Z.) followed by a comma-seperated list of items that should be in that location
  require_here: comma-seperated list of items that should be on the player's current location
  require_inventory: comma-seperated list of items that should be in the player's inventory
  equals: check if variable is equal to value (variable, value)
  less_than: check if variable is less than a certain value (variable, value)
  more_than: check if variable is more than a certain value (variable, value)
  lose: comma-seperated list of items in inventory to disappear
  gain: comma-seperated list of items to be added to the inventory
  drop: comma-seperated list of items to be moved from the inventory to the current room
  new_location: X.Y.Z value of the room this exit should take you to

info
----

Syntax::

  info():
      title:
      author:
      license:

Example::

  info():
      title: Your game name
      author: Your name
      license: Your preferred license

info allows the developer to store game-specific information such as title, 
author or license.

The title, author and license fields are required. The developer may add as 
many additional fields as they want, but it is up to the HERITAGE 
implementation if these are shown and how these are shown.

import
------

Syntax::

  import(filename)

Example::

  import(items)

import allows the developer to import other HERITAGE files in the current 
directory or a subdirectory. This is mostly to ease organising game data, but 
can also be used to import "libraries" adding a set of standard items. Do note 
that the statements in the imported file are inserted on the location the 
import statement is. If you want to overwrite imported items, make sure to do 
so AFTER the import statement.

For security and privacy reasons, only files in the current directory or a 
subdirectory may be imported.

item
----

Syntax::

  item(name.instance):

Example::

  item(dark_coat.2):
      on_examine: This is a dark coat.

name is the name of the item to create, instance is an name-unique number. 
itemname is required, and multi-word items should have the words separated by 
an underscore. instance is not required, unless you want to have multiple 
items with the same name; item(dark_coat) is valid syntax. An item and 
instance combination should only be defined once.

on_handler fields define what to do when an user types a command. In the 
example, the text "This is a dark coat" would be printed if the player types 
"look at dark coat".

room
----

Syntax::

  room(x.y.z):

Example::

  room(0.0.0):
    first_enter: This text is returned the first time someone enters this room
    description: Description text, shown on entering the room or looking
    items: pen, computer.2
    exits: portal.3, east

room allows the user to create a room on a 3 dimensional grid. The player 
always starts at the room with X, Y and Z positions 0 (room(0.0.0)).

Each x.y.z combination should only be defined once.

room accepts the following substatements::

  first_enter: The text to print upon entering this room for the first time
  description: Text shown upon entering the room (also first time if first_enter is not defined) or looking
  items: comma-seperated list of items in the room
  exits: comma-seperated list of exits in the room

var
---

Syntax::

  var(name, value)

Example::

  var(points, 0)

var initializes a variable with the given value. This can be either an integer 
(0, 2, 14, etc.), the name of another variable that has been defined before, 
or a string (do note to use "double quotes").