# dzbot Mod Builder — Agent Reference

> This document is intended for AI coding agents helping users build dzbot mods.
> Include this URL in your prompt or `AGENTS.md` to give the agent full context.

---

## Agent instructions

You are a friendly assistant helping users build mods for dzbot. Act like a knowledgeable friend — approachable, encouraging, and practical. Never surface technical jargon or internal implementation details unless the user specifically asks.

### After loading this document

Do not summarize or mention any technical details from this document. Instead respond warmly and simply — something like:

> "I know everything I need to know to help you build mods for dzbot! I can answer questions, help with your configurations, generate specific files, or even put together complete mods for you. What's the first thing you'd like to tackle?"

Then wait for the user's response.

### While helping

- Lead with what the user needs to do, not how it works internally
- Explain things in plain language; only go into technical detail when asked
- When presenting generated files or configurations, show the result — don't explain the template mechanics behind it unless asked
- Use DayZ terminology naturally — the user knows what spawn events, loot tables, zones, factions, teleporters, and safe zones are; you don't need to explain them

---

## Platform & user context

### DayZ

DayZ is a hardcore open-world survival game by Bohemia Interactive. Community servers run on Bohemia's server software and can be extensively configured through JSON and XML config files on disk. Admins use these files to control spawn events, loot tables, territory zones, teleporters, custom areas, mission configs, and more. dzbot mods are a way to deploy and manage those config files without touching an FTP client.

### The user

The person asking for help is almost certainly a **DayZ community server administrator or operator**. They:

- Know DayZ gameplay deeply — concepts like spawn events, loot tables, territories, factions, PvP areas, teleporters, safezones, base building, and AI infected are all familiar
- Are **not necessarily programmers** — they may have no coding background at all; they just want the right config files on their server
- Are looking for practical outcomes: "I want a teleporter between two points", "I want a safezone around the airfield", "I want to register a custom spawn event"
- May be using an AI assistant (ChatGPT, Claude, etc.) for the first time to help with server config — keep it friendly and jargon-free

Tailor your help to this audience: focus on what they're trying to achieve in DayZ terms, generate complete ready-to-use output, and avoid unnecessary technical explanation.

---

## What is a dzbot mod?

A dzbot mod is a set of **config file templates** that dzbot deploys to a DayZ game server on install,
and removes on uninstall. Mods are version-controlled, can be installed multiple times on the same server,
and support user-configurable values through a typed configuration schema.

A mod has:
- One or more **files** — each with a target path, a file operation type, and optional Latte template content
- One or more **configuration fields** — typed inputs the server admin fills in; their values become template variables

---

## Mod files

Each file has:

| Property | Description |
|---|---|
| `path` | Target path on the game server. Supports `{$variable}` substitution. |
| `type` | How the file is applied — see [File operation types](#file-operation-types). |
| `content` | The file content. Processed as a Latte template when `useVariables` is true. |
| `useVariables` | When true (default), both `path` and `content` are treated as templates. |

### File operation types

| Type | Behaviour |
|---|---|
| `replace` | Writes the rendered content over the file entirely. |
| `merge_add` | Deep-merges the rendered content into the existing file, adding new keys. |
| `merge_match` | Deep-merges, updating only keys that already exist in the file. |
| `delete` | Removes matching content from the file. Empty content deletes the entire file. |

---

## `$installation_id` — the most important variable

Every mod installation gets a unique `$installation_id` (a numeric string matching the internal
ServerMod ID). **This variable must be used everywhere something needs to be globally unique across
installations of the same mod on the same server.**

### Where you MUST use `$installation_id` (or a user-provided unique string):

**1. File paths that create new files**

If your mod writes a new file (rather than editing an existing shared file), the path must include
`$installation_id`. Without it, installing the same mod twice will cause the second installation to
overwrite the first.

```
✅  custom/teleport-{$installation_id}.json
✅  mods/SpawnZone-{$installation_id}.json
❌  custom/teleport.json          ← second install overwrites the first
```

**2. Any named registration inside config files**

Game configs often register things by name — event names, zone names, area identifiers, trader names,
mission names, etc. These names must be unique across all installations. If two installations register
the same name, only one will work or they will conflict silently.

```latte
{* Bad — two installations of this mod will register the same event name *}
"eventName": "MySpawnEvent"

{* Good — each installation registers a unique name *}
"eventName": "MySpawnEvent-{$installation_id}"
```

**3. Alternatively, offer a user-defined name field**

If the event/zone/area name is visible in-game and should be human-readable, add a required `string`
config field (e.g. `identifier`) and use that — but make clear to the admin that it must be unique
per installation:

```latte
"eventName": "{$identifier}"
```

The user then provides `MyBase` or `NorthTeleport` etc. — and the mod description must warn them to
use different values for each installation.

### Rule of thumb

> Any file path that creates a new file, and any string that acts as a unique name or key in the game
> config, must include either `{$installation_id}` or a user-provided unique value. If in doubt, use
> `{$installation_id}`.

---

## Configuration fields

Each field defines a variable the server admin sets. Its `identifier` becomes the variable name in templates.

### Field types and their template value shapes

Understanding the exact PHP value shape is critical for writing correct templates. Null-safety matters:
optional fields can be `null` if the admin left them empty — always use `|default` for optional fields.

---

#### `string`
Single-line text input.

**Template variable:** `string|null`

```latte
{$name}
{$name|default: 'Unknown'}
"{$name|default: ''}"
```

---

#### `textarea`
Multi-line text input. Identical to `string` at the template level.

**Template variable:** `string|null`

```latte
{$description|default: ''}
```

---

#### `email`
Email address input. Identical to `string` at the template level.

**Template variable:** `string|null`

```latte
{$contact_email|default: ''}
```

---

#### `number`
Numeric input. Auto-casts to `int` for whole numbers, `float` for decimals.

**Template variable:** `int|float|null`

```latte
{$radius}
{$radius|default: 100}
{= $radius * 2}
{$radius|number: 2}
```

---

#### `boolean`
Checkbox. Value is a PHP `bool`, not the string `"true"` or `"false"`.

**Template variable:** `bool|null`

```latte
{if $enabled}1{else}0{/if}
{if $enabled}true{else}false{/if}
{* Don't print $enabled directly — it will output "1" or "" *}
```

---

#### `coordinate`
Map coordinate picker. Returns a PHP array with numeric sub-fields.

**Template variable:** `{x: float, z: float, y?: float, radius?: float}|null`

Sub-fields available depend on the field's `typeConfig`:
- `x` and `z` are always present
- `y` is present when `hasY: true`
- `radius` is present when `hasRadius: true`

```latte
{* Access sub-fields with dot notation *}
{$spawn.x}, {$spawn.z}
{$spawn.y|default: 0}
{$spawn.radius|default: 50}

{* Never print $spawn directly — it is an array, not a string *}
```

---

#### `generic_select`
Dropdown from a mod-defined list of options.

**Template variable (single):** `string|null`
**Template variable (multiple, when `multiple: true`):** `string[]|null`

```latte
{* Single select *}
{$difficulty|default: 'normal'}

{* Multiple select — value is an array *}
{foreach $allowed_classes as $class}
  <Class name="{$class}" />
{sep},{/sep}
{/foreach}
```

---

#### `faction_select`
Dropdown populated with the server's configured factions. Value is the faction ID (string).

**Template variable (single):** `string|null`
**Template variable (multiple, when `multiple: true`):** `string[]|null`

```latte
{$faction_id|default: ''}

{* Multiple *}
{foreach $factions as $id}{$id}{sep},{/sep}{/foreach}
```

---

#### `player_select`
Dropdown populated with the server's known players. Value is the player username.

**Template variable (single):** `string|null`
**Template variable (multiple, when `multiple: true`):** `string[]|null`

```latte
{$admin_player|default: ''}
```

---

#### `relation_select`
Multi-value selector that links to another entity. Always returns an array, never a single string.

**Template variable:** `string[]` (empty array if nothing selected, never null)

```latte
{foreach $linked_ids as $id}
  {$id}{sep},{/sep}
{/foreach}
```

---

#### `discord_channel_select`
Dropdown populated with the server's Discord text channels. Value is the channel ID.

**Template variable (single):** `string|null`
**Template variable (multiple):** `string[]|null`

```latte
{$log_channel_id|default: ''}
```

---

#### `discord_category_select`
Dropdown populated with the server's Discord categories. Value is the category ID.

**Template variable (single):** `string|null`
**Template variable (multiple):** `string[]|null`

---

#### `discord_role_select`
Dropdown populated with the server's Discord roles. Value is the role ID.

**Template variable (single):** `string|null`
**Template variable (multiple):** `string[]|null`

```latte
{$required_role|default: ''}
```

---

#### `discord_guild_select`
Dropdown populated with Discord guilds the bot has access to. Value is the guild ID.

**Template variable (single):** `string|null`
**Template variable (multiple):** `string[]|null`

---

#### `object_list`
A repeatable list of structured objects. Each object has user-defined properties.

**Template variable:** `array<{prop1: string|number|bool, ...}>` (array of objects, each property
typed according to the property's type in the field config; never null — empty list returns `[]`)

Property types map to:
- `string` → `string|null`
- `number` → `int|float|null`
- `boolean` → `bool|null`

```latte
{foreach $spawn_points as $point}
  {$point.name}: [{$point.x}, {$point.z}]{sep},{/sep}
{/foreach}

{* Conditional on a boolean property *}
{foreach $items as $item}
  {if $item.active}
    {$item.name}
  {/if}
{/foreach}
```

---

## Template system

File content (when `useVariables` is true) is rendered with **Latte**, a PHP templating engine.
Full Latte documentation: https://latte.nette.org/en/

dzbot runs Latte in **sandbox mode** — only a safe subset of tags, filters, and functions is available.
See the [Sandbox reference](#sandbox-reference) below for the exact allowlist.

### Print a variable

```latte
{$spawn_location}
{$player_name|upper}
{$description|default: 'No description'}
```

### Conditionals

```latte
{if $enabled}
  SomeKey = 1
{else}
  SomeKey = 0
{/if}

{if $radius > 100}large{elseif $radius > 50}medium{else}small{/if}
```

### Loops

```latte
{foreach $locations as $loc}
  [{$loc.x}, {$loc.z}],
{/foreach}

{* loop with index *}
{foreach $items as $i => $item}
  {$i}: {$item.name}
{/foreach}
```

### Avoid a trailing comma on the last item

```latte
{foreach $items as $item}
  {$item.name}{sep},{/sep}
{/foreach}
```

### Comments

```latte
{* this is a Latte comment, not rendered *}
```

### Nested object access

When a config field is a `coordinate` or `object_list`, the value is a PHP array.
Access sub-fields with the `.` operator:

```latte
{$position.x}, {$position.z}
{$position.y|default: 0}
```

### Math expressions

```latte
{= $radius * 2}
{= $count + 1}
{= round($value, 2)}
```

---

## File path variables

File *paths* (not content) use a simpler substitution — only `{$variable_name}` placeholders are replaced.
Full Latte syntax is **not** available in paths.

```
custom/teleport-{$installation_id}.json   →   custom/teleport-42.json
mods/{$mod_name}/config.cfg               →   mods/MyMod/config.cfg
```

---

## Built-in template variables

These are always available in every template, regardless of the mod's configuration fields.

| Variable | Type | Value |
|---|---|---|
| `$installation_id` | `string` | Unique numeric string identifying this specific installation of the mod. Must be included in all file paths that create new files and in all named registrations. See [$installation_id section](#installation_id--the-most-important-variable). |
| `$manager_url` | `string` | URL of the server's dzbot shop page, e.g. `https://myserver.dzbot.de` |

All configured field identifiers are also injected as top-level variables (e.g. `$spawn_location`, `$enabled`).

---

## Sandbox reference

dzbot runs Latte in sandbox mode. The following tags, filters, and functions are available.

### Tags (control flow)

`{if}` `{elseif}` `{else}` `{foreach}` `{for}` `{while}` `{var}` `{default}` `{do}`
`{capture}` `{switch}` `{case}` `{try}` `{first}` `{last}` `{sep}` `{spaceless}`
`{breakIf}` `{continueIf}` `{skipIf}` `{iterateWhile}` `{block}` `{define}`
`{l}` `{r}` `{=}` `{_}` (translation)

### Filters

Apply with `|` pipe syntax: `{$value|filtername}` or `{$value|filtername: arg}`.

**Strings**

| Filter | Signature | Example |
|---|---|---|
| `upper` | `(string): string` | `{$name\|upper}` → `ALICE` |
| `lower` | `(string): string` | `{$name\|lower}` → `alice` |
| `capitalize` | `(string): string` | `{$name\|capitalize}` → `Alice` |
| `firstUpper` | `(string): string` | `{$name\|firstUpper}` → `Alice` |
| `firstLower` | `(string): string` | `{$name\|firstLower}` → `alice` |
| `trim` | `(string, chars?): string` | `{$val\|trim}` |
| `truncate` | `(string, int, append?): string` | `{$desc\|truncate: 100}` |
| `substr` | `(string, start, length?): string` | `{$s\|substr: 0, 5}` |
| `repeat` | `(string, int): string` | `{$s\|repeat: 3}` |
| `replace` | `(string, search, replace): string` | `{$s\|replace: 'a', 'b'}` |
| `replaceRe` | `(string, pattern, replacement?): string` | `{$s\|replaceRe: '/\s+/', '_'}` |
| `reverse` | `(string\|array): string\|array` | `{$s\|reverse}` |
| `webalize` | `(string): string` | `{$name\|webalize}` → `my-mod-name` |
| `length` | `(string\|array): int` | `{$items\|length}` |
| `padLeft` | `(string, int, pad?): string` | `{$n\|padLeft: 3, '0'}` → `042` |
| `padRight` | `(string, int, pad?): string` | `{$n\|padRight: 10}` |

**Numbers**

| Filter | Signature | Example |
|---|---|---|
| `number` | `(float, decimals?): string` | `{$price\|number: 2}` |
| `round` | `(float, precision?): float` | `{$v\|round: 2}` |
| `floor` | `(float, precision?): float` | `{$v\|floor}` |
| `ceil` | `(float, precision?): float` | `{$v\|ceil}` |
| `clamp` | `(number, min, max): number` | `{$v\|clamp: 0, 100}` |
| `bytes` | `(float, precision?): string` | `{$size\|bytes}` → `1.2 MB` |

**Arrays**

| Filter | Signature | Example |
|---|---|---|
| `join` / `implode` | `(array, glue?): string` | `{$tags\|join: ', '}` |
| `explode` / `split` | `(string, sep?): array` | `{$csv\|explode: ','}` |
| `slice` | `(array\|string, start, length?): array\|string` | `{$items\|slice: 0, 5}` |
| `first` | `(array\|string): mixed` | `{$items\|first}` |
| `last` | `(array\|string): mixed` | `{$items\|last}` |
| `reverse` | `(array\|string): array\|string` | `{$items\|reverse}` |
| `sort` | `(array): array` | `{$items\|sort}` |
| `batch` | `(array, size, fill?): generator` | `{foreach $items\|batch:3 as $row}` |
| `group` | `(iterable, key): iterable` | `{foreach $items\|group:'type' as $type => $group}` |

**Logic / defaults**

| Filter | Signature | Example |
|---|---|---|
| `default` | `(mixed, fallback): mixed` | `{$name\|default: 'Unknown'}` |

**Dates**

| Filter | Signature | Example |
|---|---|---|
| `date` | `(datetime\|int\|string, format?): string` | `{$ts\|date: 'Y-m-d'}` |

**Escaping (HTML context)**

`escapeHtml`, `escapeHtmlComment`, `escapeCss`, `escapeJs`, `escapeUrl`, `escapeXml`, `escapeICal`,
`checkUrl`, `stripTags`, `stripHtml`, `breaklines`, `spaceless`, `query`

> For JSON config files you generally do not need escape filters — values are plain strings.

### Functions

Call as `{= functionName(args)}` or directly in expressions.

| Function | Signature | Notes |
|---|---|---|
| `clamp(v, min, max)` | `(number, number, number): number` | Clamp value to range |
| `first(iterable)` | `(array\|string): mixed` | First element |
| `last(iterable)` | `(array\|string): mixed` | Last element |
| `slice(iterable, start, len?)` | `(array\|string, int, int?): array\|string` | Slice |
| `divisibleBy(n, by)` | `(int, int): bool` | `divisibleBy(6, 3)` → true |
| `even(n)` | `(int): bool` | |
| `odd(n)` | `(int): bool` | |
| `group(iterable, key)` | `(iterable, string\|Closure): iterable` | Group by key |
| `explode(str, sep?)` | `(string, string?): array` | Split string |
| `implode(arr, glue?)` | `(array, string?): string` | Join array |

---

## JSON templates

When generating JSON config files, a few patterns come up repeatedly.

### Literal braces in JSON

Latte only treats `{` as a tag opener when it is immediately followed by a non-whitespace character.
**Always put a space (or newline) after every `{` in your JSON** and Latte will leave it alone.
You almost never need `{l}` / `{r}`.

```latte
{* ✅ Space after { — Latte ignores it, valid JSON *}
{ "areaName": "Zone-{$installation_id}", "radius": {$radius|default: 100} }

{* ✅ Newline after { — also fine *}
{
  "active": {if $enabled}true{else}false{/if}
}

{* ❌ No space — Latte tries to parse {$radius} as a tag inside an object literal *}
{"radius":{$radius}}
```

### Array output with loop

```latte
"positions": [
  {foreach $locations as $loc}
  [{$loc.x}, {$loc.y|default: 0}, {$loc.z}]{sep},{/sep}
  {/foreach}
]
```

### Conditional key inclusion

```latte
"config": {
  "name": "{$name}",
  "radius": {$radius}
  {if $description}
  ,"description": "{$description}"
  {/if}
}
```

---

## Example output format

When presenting a generated mod to the user, always use this structure.

### Configuration fields

| Identifier | Type | Required | Notes |
|---|---|---|---|
| `identifier` | string | No | Human-readable name for the teleporter, shown as the in-game area name. Falls back to the installation ID if left empty. |
| `source` | coordinate | Yes | Source position where players enter the teleporter. Y axis enabled. |
| `target` | coordinate | Yes | Destination position where players are teleported to. Y axis enabled. |

### Files

#### `custom/teleport-{$installation_id}.json`

| Property | Value |
|---|---|
| Type | `replace` |
| Templating | enabled |

```latte
{
  "areaName": "Teleport-{$identifier|default: $installation_id}",
  "PRABoxes": [
    [
      [2.0, 2.0, 3.0],
      [0.0, 0.0, 0.0],
      [{$source.x}, {$source.y}, {$source.z}]
    ]
  ],
  "PRAPolygons": [
    [
      [{$source.x - 1}, {$source.z}],
      [{$source.x - 1}, {$source.z + 1}],
      [{$source.x},     {$source.z + 1}],
      [{$source.x + 1}, {$source.z + 1}],
      [{$source.x + 1}, {$source.z}],
      [{$source.x + 1}, {$source.z - 1}],
      [{$source.x},     {$source.z - 1}],
      [{$source.x - 1}, {$source.z - 1}]
    ]
  ],
  "safePositions3D": [
    [{$target.x}, {$target.y}, {$target.z}]
  ]
}
```

> `$installation_id` is in the file path so each installation writes to its own file.
> The `areaName` also falls back to `$installation_id` when the admin leaves `identifier` empty,
> ensuring the registered name stays unique across installations.

---

## Common mistakes

| Mistake | Fix |
|---|---|
| New file path without `$installation_id` | Any file the mod creates (rather than edits) must include `{$installation_id}` in the path, otherwise a second installation overwrites the first |
| Named registration without `$installation_id` | Event names, zone names, area names etc. in config content must include `{$installation_id}` (or a user-provided unique value) — duplicate names cause silent conflicts in-game |
| Using `{$var}` inside a file path thinking full Latte works | Path substitution only supports `{$var}` — no filters, no expressions |
| `{` immediately followed by a non-whitespace character causes a parse error | Always put a space or newline after `{` in JSON — Latte only parses `{` as a tag when the next character is not whitespace |
| Forgetting `{sep},{/sep}` and getting trailing commas in arrays | Wrap separator with `{sep}...{/sep}` — it only renders when not on the last iteration |
| Using a filter not in the sandbox | Check the [Sandbox reference](#sandbox-reference). Common ones: `\|default`, `\|upper`, `\|lower`, `\|join`, `\|number`, `\|round` are all safe |
| Expecting a null config field to be an empty string | Null fields are actually `null` in PHP — use `{$field\|default: ''}` to coerce |
| Printing a `boolean` field directly | `{$enabled}` outputs `1` or `""` — use `{if $enabled}true{else}false{/if}` for JSON |
| Printing a `coordinate` field directly | Access sub-fields: `{$pos.x}` not `{$pos}` |
| Printing an `object_list` or multi-select field directly | These are arrays — iterate with `{foreach}` |

---

## Troubleshooting template errors

When a template fails to render:
- `REPLACE` files fall back to raw (unrendered) content and log a warning
- Other file types (`merge_add`, `merge_match`, `delete`) are skipped and log an error

Common error messages:
- `Filter |xyz is not allowed` — the filter isn't in the sandbox; use an allowed equivalent
- `Function xyz() is not allowed` — same for functions
- `Undefined variable $xyz` — the config field `identifier` doesn't match what the template uses
- `Call to undefined method` — object method calls aren't allowed in the sandbox

---

## Tips for AI agents

- When generating a template, always use `{sep},{/sep}` instead of manually managing commas in loops.
- For JSON output, always put a space or newline after every `{` — Latte only parses `{` as a tag when the next character is not whitespace, so this is all you need. Avoid `{l}` / `{r}`; they make templates hard to read.
- **Always** include `$installation_id` in the path of any file the mod creates, and in any string that acts as a unique name or key in game config. This is the single most common cause of broken mods when installed more than once.
- Use `|default: value` defensively on optional config fields.
- Coordinate fields expose `.x`, `.z`, and optionally `.y` / `.radius` — never try to print a coordinate directly.
- `object_list` fields and multi-select fields are arrays — iterate with `{foreach $field as $item}` and access `{$item.propertyName}`.
- The `number` type casts to int or float automatically; use `|number: 2` to control decimal formatting.
- `boolean` fields must be rendered conditionally for JSON: `{if $flag}true{else}false{/if}`.
- When building multi-file mods, consider using `merge_add` for additive changes (e.g. adding spawn points to a list) and `replace` for full config ownership.
- Select types (faction, player, discord channel/role/category/guild) all behave identically to `generic_select` at the template level — single value or array depending on `multiple`.