
NAME

  WolfMUD zone files

DESCRIPTION

  This document describes details for the WolfMUD zone files. WolfMUD zone
  files are written in the WolfMUD record jar format, as described in the
  document wolfmud-record-format.txt, and have a .wrj extension.

  When started the WolfMUD server will try to load zone files with a .wrj
  extension from the zones sub directory, located in the server's data
  directory. For more details see: running-the-server.txt

  Zone files contain an option zone header record giving brief information
  about the zone such as its name and the name of the author. The rest of the
  records detail locations and objects within the world.

  The following is an example of a zone file with an optional header record, a
  location record, a narrative record and an item record:


    // Copyright 2016 Andrew 'Diddymus' Rolfe. All rights reserved.
    //
    // Use of this file is governed by the license in the LICENSE file
    // included with the source code.
    %%
          Ref: ZINARA
         Zone: City of Zinara
       Author: Andrew 'Diddymus' Rolfe

    This is the city of Zinara.
    %%
           Ref: L1
         Start:
          Name: Fireplace
       Aliases: TAVERN FIREPLACE
         Exits: E→L3 SE→L4 S→L2
     Inventory: L1N1

    You are in the corner of the common room in the dragon's breath tavern. A
    fire burns merrily in an ornate fireplace, giving comfort to weary
    travellers. The fire causes shadows to flicker and dance around the room,
    changing darkness to light and back again. To the south the common room
    continues and east the common room leads to the tavern entrance.
    %%
           Ref: L1N1
     Narrative:
          Name: an ornate fireplace
         Alias: FIRE FIREPLACE

    This is a very ornate fireplace carved from marble. Either side a dragon
    curls downward until the head is below the fire looking upward, giving the
    impression that they are breathing fire.
    %%
          Ref: O1
         Name: a curious brass lattice
      Aliases: LATTICE
     Location: L1
        Reset: AFTER→2m JITTER→1m
      OnReset: There is a gentle, musical ping and a curious brass lattice
               suddenly appears from nowhere.
      Cleanup: AFTER→10m
    OnCleanup: The curious brass lattice starts to slowly spin. It rapidly
               gains speed and then suddenly collapses in on itself and
               disappears.
       Action: AFTER→5m JITTER→2m30s
     OnAction: The lattice quietly chimes.
             : The lattice quietly hums.

    This is a finely crafted, intricate lattice of fine brass wires forming a
    roughly ball shaped curiosity.
    %%

FIELD DATA TYPES

  Depending on the field name the format of the data can be required to be in
  a specific format. This section lists the different formats.

  STRING
    The data is a simple string of characters.

  KEYWORD
    The data is a single case insensitive word.

  KEYWORD LIST
    The data is a list of whitespace separated, case insensitive words.

  PAIR LIST
    The data is a white space separated list of pairs. Each pair is separated
    by a non-digit or non-letter character. For example:

      Exits: E→L3 SE→L4 S→L2

    There are three pairs: E→L3, SE→L4 and S→L2. Each pair is separated by '→'
    which is a non-digit and non-numeric.

  STRING LIST
    The data is separated into strings using a colon (:) as a separator. For
    example:

      Actions: The rabbit hops around a bit.
             : You see the rabbit twitch its little nose, Ahh...

    This defines two actions.

  KEYED STRING
    The data is separated into a keyword and a string. The keyword should be a
    single word followed by a non-letter and non-numeric separator. For
    example:

      Vetoes: GET→You cannot get it!

    This defines a veto with the keyword 'GET' and the string "You cannot get
    it!". The separator used is the '→' character.

  KEYED STRING LIST
    The data is a list of keyed strings. This combines the STRING LIST and
    KEYED STRING types. For example:

      Vetoes: GET→You cannot get it!
            : PUT→It does not want to be put anywhere!

    This defines two vetoes separated by a colon. Each veto is a keyword
    followed by a string. The keyword and string are separated using the '→'
    character.

ZONE HEADER RECORD

  The zone header record is optional. If present it can contain the following
  fields:

  AUTHOR: <STRING>
    The name of the author of the zone.

  REF: <KEYWORD>
    REF is a reference to the zone. The reference should be unique for each
    zone available. It is used for ZONELINKS fields so that different zones
    can be linked together.

  ZONE: <STRING>
    A brief name for the zone.

  FREE TEXT BLOCK
    A description for the zone.

ZONE RECORDS

  Additional zone records after the optional zone header record are used to
  define locations and objects. They are defined by using a combination field
  types. Different types of objects can be defined by combining different
  fields together. The following are the different fields that are available:

  ACTION: <PAIR LIST>
    ACTION is used to specify how often an item displays an action message.
    The pairs that are valid for ACTION are:

      AFTER→<period>
      JITTER→<period>

    For example:

      ACTION: AFTER→5m JITTER→2m30s

    AFTER and JITTER specify the period to wait between messages to be between
    AFTER and AFTER+JITTER. In the example an action will occur every five to
    seven and a half minutes.

    If AFTER and JITTER are not specified the minimum period will be 1 second.

    The action messages to be displayed are specified via ONACTION. See
    ONACTION for more details.

  ALIAS: <KEYWORD LIST>
    A list of keywords used by players to interact with something. For
    example: LATTICE

  CLEANUP: <PAIR LIST>
    CLEANUP is used to specify how long to wait after an item is dropped
    before it is automatically cleaned up and either reset or disposed of. If
    an item does not have a CLEANUP it will be left laying around. The pairs
    that are valid for CLEANUP are:

      AFTER→<period>
      JITTER→<period>

    For example:

      CLEANUP: AFTER→2m JITTER→1m

    AFTER and JITTER specify the period to wait before cleaning up the item to
    be between AFTER and AFTER+JITTER.

    If AFTER and JITTER are not specified the minimum clean up period will be
    1 second.

    Custom messages can be displayed when an item is cleaned up. See
    ONCLEANUP for more details.

  DOOR: <PAIR LIST>
    A DOOR field defines anything door-like that can block a direction of
    travel. For example a door, a gate, a panel or a bookcase. The pairs
    that are valid for a DOOR are:

      EXIT→<direction>
      RESET→<period>
      JITTER→<period>
      OPEN→<boolean>

    For example:

      DOOR: EXIT→E RESET→2m JITTER→1m OPEN→false

    EXIT defines the direction that is blocked when the DOOR is closed. The
    direction can be specified in long or short form (SEE EXITS). If an EXIT
    is not specified the DOOR will not block travel but can still be open and
    closed - perhaps it's just leaning against a wall? :)

    OPEN defines whether the door is initially open or closed. If omitted
    defaults to false (closed). Just specifying OPEN with no value is
    a shorthand for OPEN→True.

    RESET defines the delay after which the door should automatically be reset
    to its initial state of open or closed - as defined by OPEN above. The
    period should be given in the form: 0h0m0s for example "30s" for 30
    seconds. A value equivalent to a duration of zero length disables the
    automatic reset. For example 0h, 0m or 0s. If omitted defaults to 0s.

    JITTER defines a maximum random amount of time to add to the RESET delay.
    That is, the actual delay will be between RESET and RESET+JITTER. In the
    example a JITTER of 1m will causing the DOOR to reset after a delay of
    between 2 and 3 minutes (between 2m and 2m+1m). A JITTER of 0s adds no
    randomness to the RESET delay. If omitted defaults to 0s.

    If RESET and JITTER are both set to 0s the DOOR will not automatically
    reset to its initial state.

    NOTE: A DOOR attribute should only be added to narrative items in a
    location. Adding a DOOR directly to a location or a moveable item may
    result in unexpected/odd behaviour.

  EXITS: <PAIR LIST>
    An EXITS field defines something as a location, allowing for very loose
    definitions of what a location is. Each pair in the list should consist of
    a direction followed by a non-digit, non-letter separator followed by a
    reference to another location. Exit directions can be given in long or
    short form. The long and short form directions available are: North - N,
    Northeast - NE, East - E, Southeast - SE, South - S, Southwest - SW, West -
    W, Northwest - NW, Up - U, Down - D. Directions are case insensitive as
    are the references. An example might be: E→L3. This implies that going
    east from the location defining the exits will lead to the location with a
    REF field of L3. If an invalid reference is given the exit will be
    ignored. As references are only unique within separate zone files exits
    between locations in different zones need to use a ZONELINKS field.

    When adding exits it should be noted that they are usually added as
    opposing pairs. For example: going east from A leads to B, going west from
    B leads back to A. As the exits are added to A and B independently this
    need not always be the case.

    An EXITS pair may be left incomplete. For example, S or S→. This is
    convenient as a reminder when developing a zone. Such incomplete pairs
    will be ignored. To raise a warning when the zone is loaded use an
    invalid reference instead. For example, S→X

    If an EXITS field is added to something an inventory will be automatically
    added as well even if there is no specific INVENTORY field.

  INVENTORY: <KEYWORD LIST>
    The INVENTORY field defines something as being a container or location. It
    may be followed by a list of space separated references. Each reference
    will be looked up and the something it uniquely references will be placed
    into the inventory. The same reference may appear in multiple INVENTORY in
    which case a copy of the original something will be made. As an example:
    INVENTORY: O1 - this says to put the something defined as O1 into this
    inventory. See also LOCATION.

    It is possible to put containers inside other containers. It is also
    possible, but very confusing, to put locations inside locations or inside
    containers. However you cannot put something or a location directly inside
    itself.

    It is also possible for players to enter containers even though it may not
    have EXITS defining it as an actual location.

  LOCATION: <KEYWORD LIST>
    LOCATION fields are used to put something into one or more inventories.
    Whereas an INVENTORY field says 'put these items here' a LOCATION field
    says 'put this item there and there'. Both LOCATION and INVENTORY have the
    same effect but LOCATION allows where something is put to be defined with
    the actual something, whereas INVENTORY allows you to define what is at a
    location with the location.

    When deciding whether to use LOCATION or INVENTORY to place things as a
    rule of thumb use LOCATION for things unique to a location, such as
    narratives, and use INVENTORY to place things in multiple places.

  NAME: <STRING>
    A short descriptive name. For example: a curious brass lattice

  NARRATIVE:
    A NARRATIVE field marks something as being immoveable. Narratives are also
    not specifically listed in containers or locations with other objects.
    Narratives can be used to provide additional details about something
    described in a description. For example a room might say there is a
    fireplace. By defining the fireplace as a narrative with a name,
    description and alias, and adding it to the location's inventory the
    fireplace may be examined by players. Apart from being immoveable and not
    specifically listed narratives behave like normal objects. For example
    they can have inventories and contain other objects.

  ONACTION: <string list>
    ONACTION can be used to provide action messages that are emitted by an
    item. For example:

      OnAction: The lattice quietly chimes.
              : The lattice quietly hums.

    The messages will be displayed with a frequency defined by ACTION. Every
    time ONACTION fires one message to display will be picked at random from
    the messages defined by ONACTION.

    The message will be displayed if the item is in a location where it will
    be seen. If the action occurs inside a container it will not be seen, and
    no message displayed.

    See also ACTION for how to schedule action messages for an item.

  ONCLEANUP: <string>
    ONCLEANUP can be used to provide a custom message when an item is cleaned
    up and removed from play. For example:

      OnCleanup: The curious brass lattice starts to slowly spin. It rapidly
                 gains speed and then suddenly collapses in on itself and
                 disappears.

    The message will be displayed if the item clean up occurs in a location
    where it will be seen. If the clean up occurs inside a container it will
    not be seen, and no message displayed.

    If an item does not have an ONCLEANUP and the clean up would be seen a
    default message will be displayed of the form:

      "You are sure you noticed <item> here, but you can't see it now."

    If a message should not be displayed, even if the clean up would otherwise
    be seen, specify an ONCLEANUP with no message. In this case the item will
    simply disappear with no notification at all.

    See also CLEANUP for how to schedule an item for automatic clean up.

  ONRESET: <string>
    ONRESET can be used to provide a custom message when an item is reset or
    respawned and put back into play. For example:

      OnReset: There is a gentle, musical ping and a curious brass lattice
               suddenly appears from nowhere.

    The message will be displayed if the item reset or respawn occurs in a
    location where it will be seen. If an item is reset or respawned within a
    container the message will be displayed at the location where the
    container is located. For example, assume there is a pond. The pond is a
    narrative container that contains a 'fish of gold'. The ONRESET for the
    fish is:

      OnReset: A man enters. There is a gentle plop as he drops something into
               the pond before he walks off again.

    This message will be seen by players at the location where the pond is,
    even though the fish is resetting in the pond and not in the actual
    location.

    If an item does not have an ONRESET and the reset or respawn would be
    seen, that is the reset is not in a container, a default message will be
    displayed of the form:

      "You notice <item> that you didn't see before."

    If a message should not be displayed, even if the reset or respawn would
    otherwise be seen, specify an ONRESET with no message. In this case the
    item will simply appear with no notification at all.

    See also RESET for how to schedule an item for automatic resets and
    respawning.

  REF: <KEYWORD>
    REF is a unique reference to something. It only needs to be unique within
    the zone file it is defined in. It is helpful if standard reference
    prefixes are used such as 'L' for locations and 'O' for object. Although
    this is not essential and not enforced. For example: L1

  RESET: <PAIR LIST>
    RESET is used to specify how and when an item resets or respawns. The
    pairs that are valid for RESET are:

      AFTER→<period>
      JITTER→<period>
      SPAWN→<boolean>

    For example:

      RESET: AFTER→2m JITTER→1m SPAWN→true

    AFTER and JITTER specify the reset or respawn period to be between AFTER
    and AFTER+JITTER. If SPAWN is false this is the period after which the
    item will be reset and placed back into the game after being disposed of.
    If SPAWN is true it is the period after which a new copy of the item will
    appear in the game - with or without the previous copy being disposed of
    first.

    If AFTER and JITTER are not specified the minimum reset period will be 1
    second. If SPAWN is not specified it will default to false.

    Just specifying SPAWN with no value is a shorthand for SPAWN→True.

    NOTE: When an item is disposed of and does not have a reset attribute it
    will be removed from play until the server is restarted.

    Custom messages can be displayed when an item is reset or respawned. See
    ONRESET for more details.

  START:
    The START field defines a location as a starting point where players may
    appear in the world. It is only applicable for records that also define an
    EXITS field, otherwise it is ignored.

  VETOES: <KEYED STRING LIST>
    The VETOES field defines commands that cannot be used on an object and
    reasons why. For example:

      VETOES: GET→You cannot get the magical stone.
            : EXAMINE→You try to examine the magical stone but doing so makes
              your eyes water and sting.

    If added to the definition of 'a magical stone' this would prevent it from
    being taken or examined, giving the specified reasons for each.

  ZONELINKS: <PAIR LIST>
    WolfMUD allows worlds to be created as separate zones, possibly authored
    by different people, which are then linked together using ZONELINKS. Using
    ZONELINKS also makes it easy to identify the places where zones link
    together. A ZONELINK works in exactly the same way as an EXITS field. Each
    pair in the list should consist of a direction followed by a non-digit,
    non-letter separator followed by a reference to another location. However
    for ZONELINKS the reference to another location should be a zone unique
    reference followed by a non-digit, non-letter separator followed by a
    reference to a location. For example: S→ZINARASOUTH:L1 - this defines a
    ZONELINKS where going south leads to the location with REF L1 in the zone
    with REF ZINARASOUTH.

    When adding exits using ZONELINKS it should be noted that they are usually
    added as opposing pairs. For example: going east from ZONE1:A leads to
    ZONE2:A, going west from ZONE2:A leads back to ZONE1:A. As the exits are
    added to ZONE1:A and ZONE2:A independently this need not always be the
    case.

    A ZONELINKS pair may be left incomplete. For example: S, S→, S→ZINARA or
    S→ZINARA:. This is convenient as a reminder when developing a zone. Such
    incomplete pairs will be ignored. To raise a warning when the zone is
    loaded use an invalid reference instead. For example, S→X:

    When a ZONELINKS field links to something an inventory will be added
    automatically to the target being linked to even if there is no specific
    INVENTORY field for the target.

  FREE TEXT BLOCK
    The free text block is used to define descriptions for things. It's start
    is signified by a single blank line separating it from preceding fields.
    The end of the free text block is signified by either a record separator
    consisting of a line with only two percent signs '%%' or the end of the
    file is reached. If a record consists of a description only and no fields
    the preceding blank line is not required. Within a free text block blank
    lines and leading whitespace is preserved.

SEE ALSO

  configuration-file.txt, wolfmud-record-format.txt, running-the-server.txt

COPYRIGHT

  Copyright 2017 Andrew 'Diddymus' Rolfe. All rights reserved.

  Use of this source code is governed by the license in the LICENSE file
  included with the source code.

