Zone Templates

Zone templates are where zones come alive. A template is a collection of commands and triggers that handle loading NPCs and items throughout the zone. Templates, combined with config files, replace the old .zon files.

Features

• No max load: Max loads are no longer needed. Each zone command keeps track of the entities it loads, and refreshes them as needed.
• Individual refresh timers: Each command can specify its own refresh time, or use the default zone refresh time.
• Instance flags: You can set flags on items and NPCs as you load them and it only applies to that instance. This means you don't need multiple copies of an NPC to have, for example, sentinel and non-sentinel versions.
• No distro rooms: Every command can take an optional room pattern argument that can specify a subset of rooms to randomly execute the command in. This removes the need for distro rooms by allowing you to specifically target loads towards sectors and subzones.
• Triggers: Triggers allow you to execute a list of commands based on events that happen in your zone. This can allow you to create truly dynamic events.
• Quantities: A single command can specify a quantity of items or NPCs to load, greatly reducing the number of commands needed to populate a zone.
• Randomized weapons: Easily load a random weapon on any NPC.

Template Fields

• name: The name of this template. This name will be used wherever this template is loaded.
• resetTime: The default number of minutes until this zone will be refreshed. This is optional, and overrides the base zone refresh time from the config file for all commands in this template.
• commands: A list of commands to execute when this template is applied and refreshed.
• triggers: A list of triggers to listen for.

Example

A template file consists of a name, a list of commands, and a list of triggers.

{
  "name": "example",
  "commands": [
    {
      "command": "load npc",
      "vnum": 98303,
      "quantity": 10,
      "resetTime": 15,
      "equipment": [98310, 98309, 98311],
      "weapons": [98335, 98336, 98337],
      "room": 21
    },
    {
      "command": "load item",
      "vnum": 98329,
      "room": 21,
      "equipment": [33815],
      "contentQuantity": 25
    },
    {
      "command": "set exit",
      "room": 21,
      "exit": "south",
      "flags": {
        "exitFlags": ["closed"]
      }
    }
  ],
  "triggers": [
    {
      "trigger": "NPC Death",
      "npcVnum": 98301,
      "resetTime": 40,
      "commands": [
        {
          "command": "message",
          "delay": 8,
          "text": "{{crimson}}NPC DEATH{{/}} has been triggered"
        }
      ]
    }
  ]
}

Zone commands

Zone commands make up the bulk of template files. When listed in the commands array, they will be executed when the template is first loaded as well as when they refresh. When listed as part of a trigger, the commands will be executed when the specified conditions are triggered.

Each command uses a similar set of fields, but not all properties are available to each command. They can be used in any order. Check the command documentation to learn how to use each one.

Standard fields

The following fields are standard and can be used in any zone command:

• resetTime: The amount of time in seconds until this command is executed again. By default, each command will use the zone's reset time, but you can override it by setting this field.

• chance: The percentage chance from 1-100 that this command will be executed at each reset. If omitted, the default chance is 100%.

• delay: The time in ticks (1/4 of a second) until the command is executed. You can use this to delay loading something until some time after a boot or a reset.

• chain: If true, the current command will only execute if the previous command was successful. This is useful for chaining together multiple commands triggered by a single rare load.

Standard expanded fields

The following expanded fields are used in multiple command types.

Items

The items field is commonly used when loading NPCs or filling chests and the like with gear. Unlike the equipment and weapons fields, items loaded via this field do not repop by default. Generally, use this field for loading gear desirable by PCs, and the others for stock items intended for flavor.

• name: No use in game, but helpful for commenting the file. Optional.
• vnum: The vnum of the item to load.
• chance: The percentage chance that it will load. Optional. Defaults to 100.
• reload: Controls whether this item can reload after the first execution. Optional. Defaults to false.
• quantity: Use this when loading a limited amount of items with a zone command whose quantity is greater than 1. The item will then only load x number of times regardless of how many NPCs are loaded from the command. If left blank, the item will load the same number of times specified in the command quantity. See the second example below.

  {
      "comment": "Master Chef",
      "command": "load npc",
      "vnum": 98328,
      "room": 98398,
      "items": [
        {
          "name": "ladle",
          "vnum": 98339
        }
      ]
    },

In the next example, we load 8 burly sailors all over the zone. Only one of them has a shiny golden ring that loads at boot though, so by setting the quantity on the item field to 1, it will limit loading them on just the first sailor. If omitted, it would load 8 of them at boot.

  {
      "comment": "Burly Sailors",
      "command": "load npc",
      "vnum": 98301,
      "weapons": [98336, 98335],
      "loadRooms": [
        {"distro": "Main Cavern", "quantity": 3},
        {"distro": "Exterior Beach", "quantity": 2},
        {"distro": "Smuggler Ship", "quantity": 1},
        {"vnum": 98397, "quantity": 1},
        {"vnum": 98383, "quantity": 1}
      ],
      "items": [
        {
          "name": "shiny golden ring",
          "vnum": 98328,
          "quantity": 1
        }
      ],
    }

Load rooms

This field is used in most zone commands and triggers to define a subset of rooms in the zone. In some commands, like triggers, this is a single field definition. Most commonly, this is defined as an array in an NPC or item load command, where each row defines a quantity of things to load. See the second example for more detail.

• vnum: A specific room vnum.
• vnums: An array of room vnums. One will be chosen at random.
• vnumStart: Used with vnum_end to create a range of vnums to choose from at random.
• vnumEnd: Used with vnum_start to create a range of vnums to choose from at random.
• sector: A sector name to restrict the load to. Used with the vnum range fields. Room Sector List
• subzone: A subzone name to restrict the load to. Used with the vnum range fields.
• distro: The name of a distro to use for loading. Defined in the template config file.

"loadRooms": [
  {"vnumStart": 98300},
  {"vnumEnd": 98399},
  {"sector": "desert"},
  {"subzone": "desert"}
]

In the following example, we load 8 burly sailors from the same command, specifying where and how many to load in the loadRooms array:

  {
      "comment": "Burly Sailors",
      "command": "load npc",
      "vnum": 98301,
      "weapons": [98336, 98335],
      "loadRooms": [
        {"distro": "Main Cavern", "quantity": 3},
        {"distro": "Exterior Beach", "quantity": 2},
        {"distro": "Smuggler Ship", "quantity": 1},
        {"vnum": 98397, "quantity": 1},
        {"vnum": 98383, "quantity": 1}
      ]
    }

Flags

This field contains all of the flags used throughout the game.

• npc: A list of NPC ACT flags to apply. Mob Act Flags
• affects: A list of affect flags to apply. Affect Flags
• templates: A list of racial templates to apply. Race Templates
• exitFlags: A list of exit flags to apply. Exit flag values are nobits, is door, closed, locked, pickable, secret, blocked, pickproof, trapped.

"flags": {
  "npc": ["aggressive"],
  "templates": ["undead"],
  "affects": ["haste", "detect invisibility"]
}

Template load

The template load field contains a few standard fields used in template loading.

• name: This is the name of the template to load. This should match the name field in the template file that you want to load.
• mode: When loading a template, you can choose whether it overlays the existing commands or replaces them. The options are overlay or replace. It will default to overlay.
• chance: This is the 0-100% chance to load the template. Defaults to 100.

"template": {
  "name": "NPCs",
  "mode": "overlay"
}