# Configuration

**Version:** 1.0.0

Events is configured in `mods/kyuubisoft_events/config.json`. The file is written with the default values on the first start.

- **Most options are also in the admin window** (`/kseventadmin`, pages **Rules** and **Build field**). Changes there apply at once and are written to the file shortly after.
- **Edit the file while the server is stopped**, or use `/kseventadmin reload` after editing it.
- **Values out of range are repaired** when the file is read (an unknown time zone becomes the server clock), so a hand-edited file never stops the mod. The ranges are listed below.
- **There are no economy values here.** Rewards belong to each event and are empty for new events.

---

## Overview

```json
{
  "configVersion": 1,
  "timezone": "system",
  "reminders": { "minutesBefore": [60, 10, 1], "toast": true, "chat": true, "raven": true },
  "announce": { "startToAll": true },
  "contest": { "buildMinutes": 60, "voteMinutes": 20, "ceremonyMinutes": 5, "lateSignupMinutes": 10, "minParticipants": 2 },
  "meeting": { "durationMinutes": 60 },
  "travel": { "opensMinutesBefore": 10, "warmupSeconds": 3, "cancelDistance": 1.0, "returnWindowMinutes": 30 },
  "fields": { "plotSize": 24, "pathWidth": 4, "resetBeforeNext": true, "resetLeadMinutes": 5 },
  "voting": { "minVotes": 3, "anonymous": true, "voters": "PARTICIPANTS_AND_PRESENT", "releaseOnSuspicious": false, "newAccountHours": 24 },
  "attendance": { "radius": 32, "afkMinutes": 2, "graceMinutes": 5 },
  "hud": { "countdownMinutesBefore": 10 },
  "history": { "keepDays": 90 }
}
```

`configVersion` is managed by the mod; leave it as it is.

---

## Time and reminders

In the admin window: **Rules** → **Time and reminders** and **Channels**.

| Option | Default | Range | Meaning |
|--------|---------|-------|---------|
| `timezone` | `"system"` | `system` or a time zone id | The time zone of all event times. `"system"` is the server clock; otherwise an id such as `Europe/Berlin`. Changing it moves the planned dates to the new zone |
| `reminders.minutesBefore` | `[60, 10, 1]` | each 1–1440; the admin window takes up to 5 | Reminder times for **new** events. Each event keeps its own times, set on the **Plan** page |
| `reminders.toast` | `true` | | Reminders as a card at the top of the screen |
| `reminders.chat` | `true` | | Reminders as a chat line |
| `reminders.raven` | `true` | | Reminders as a note on the whisper stone, also for players who are offline. Only with KyuubiSoft Whisperstone |
| `announce.startToAll` | `true` | | The start and the ceremony are announced to everyone online. Off: only to those taking part (signed up, rating on the field, or present at a meeting) |

Players choose which dates remind them: all events, only events they joined (default) or off. Cancellations reach everyone signed up through the same channels.

---

## Flow

In the admin window: **Rules** → **Flow**.

| Option | Default | Range | Meaning |
|--------|---------|-------|---------|
| `contest.buildMinutes` | `60` | 1–1440 | Build time of **new** build contests |
| `contest.voteMinutes` | `20` | 1–1440 | Voting time of **new** build contests |
| `contest.ceremonyMinutes` | `5` | 0–120 | Ceremony time of **new** build contests |
| `contest.lateSignupMinutes` | `10` | 0–1440 | Players can still join a contest this many minutes after its start, while plots are free |
| `contest.minParticipants` | `2` | 1–100 | A contest with fewer sign-ups at its start is cancelled, and everyone signed up is told. An admin start ignores it. Meetings always take place |
| `meeting.durationMinutes` | `60` | 1–1440 | Duration of **new** meetings |
| `hud.countdownMinutesBefore` | `10` | 0–1440 | The event card at the left edge counts down from this many minutes before the start |

The phase lengths of an event are set per event on the **Plan** page; the values here only fill the form of a new event. Only `lateSignupMinutes`, `minParticipants` and `countdownMinutesBefore` are on the **Rules** page.

---

## Travel

In the admin window: **Rules** → **Flow** (**Travel opens**) and **Travel**.

| Option | Default | Range | Meaning |
|--------|---------|-------|---------|
| `travel.opensMinutesBefore` | `10` | 0–1440 | **Travel there** works from this many minutes before the start until the end |
| `travel.warmupSeconds` | `3` | 0–60 | Seconds of standing still before the trip |
| `travel.cancelDistance` | `1.0` | 0.1–16 | Moving further than this many blocks during the warm-up cancels the trip. Only in the file |
| `travel.returnWindowMinutes` | `30` | 0–1440 | **Back where I was** works until this many minutes after the end |

Taking damage during the warm-up also cancels the trip. Trips from dungeon and minigame instances are never possible; the **Rules** page shows this as **Not from instances · always**.

---

## Build fields

These are the defaults for **new** build fields and the timing of the field reset. Each field keeps its own plot size, path, locked plots, themes and reset switch, set on the **Build field** page.

| Option | Default | Range | Meaning |
|--------|---------|-------|---------|
| `fields.plotSize` | `24` | 4–128 | Plot size in blocks (square) |
| `fields.pathWidth` | `4` | 0–32 | Width of the paths between plots, in blocks |
| `fields.resetBeforeNext` | `true` | | New fields are reset to their empty state before the next contest |
| `fields.resetLeadMinutes` | `5` | 1–60 | The reset starts this many minutes before a contest starts. Only in the file |

### How the plots are laid out

The field is the rectangle of the Claims server zone, made of whole chunks (32 × 32 blocks). Events fits as many plots as possible: columns = (width + path) ÷ (size + path), rows likewise. The rest is spread evenly as a margin around the plots. Plots are numbered row by row from the north (smallest z) and from west to east. Only plots that lie fully inside the zone count.

Example: a zone of 4 × 3 chunks (128 × 96 blocks) with plots of 24 and paths of 4 gives 4 × 3 = 12 plots.

A new size or path applies from the next contest on.

### The field reset

- When a field is created, the empty state is taken from the admin's height: 4 blocks below and 60 blocks above. **Save empty state** stores the blocks of that box.
- The builds of a contest stay on the field as an exhibition. 5 minutes before the next contest on that field (and only once it has enough sign-ups), Events puts the saved empty state back, spread over a few seconds.
- Anyone on the field is first taken 6 blocks outside its nearest edge and told why. Nothing is changed while somebody is still on it.
- The contest waits for the reset for at most 10 minutes. If the reset fails or takes too long, the contest uses the next field of the event's list, and the failed field's reset switches off until an admin chooses **Retry reset** or `/kseventadmin field retry <field>`.
- A server stop during the reset does not switch it off; it runs again after the restart.
- Chest contents and items lying on the ground are not part of the empty state.

---

## Voting

In the admin window: **Build field** → **Rating**. These rules hold for every build field.

| Option | Default | Range | Meaning |
|--------|---------|-------|---------|
| `voting.minVotes` | `3` | 1–100 | A plot is only ranked with at least this many votes. The own plot never counts |
| `voting.anonymous` | `true` | | Builders stay anonymous until the ceremony. The build is rated, not the name |
| `voting.voters` | `PARTICIPANTS_AND_PRESENT` | `PARTICIPANTS`, `PARTICIPANTS_AND_PRESENT` | Who may rate: those signed up, or also everyone who stands on the field during the voting (switch **Everyone on the field may rate**) |
| `voting.releaseOnSuspicious` | `false` | | A result with suspicious votes waits until an admin releases it (**Result only after release**) |
| `voting.newAccountHours` | `24` | 0–720 | A vote counts as suspicious when Events first saw the voter less than this many hours before the vote. Only in the file |

- **Ranking:** the average of all votes, shown with one decimal. A tie on the shown average goes to the plot with more votes, then to the earlier sign-up.
- **Suspicious votes:** votes of new accounts, and votes of players who rated at least 3 plots with only 1s and 5s. Admins see them in the **Overview** and can strike or restore single votes; the ranking is recalculated.

---

## Attendance

In the admin window: **Rules** → **Attendance**. Used for meetings.

| Option | Default | Range | Meaning |
|--------|---------|-------|---------|
| `attendance.radius` | `32` | 1–512 | Blocks around the meeting point that count |
| `attendance.afkMinutes` | `2` | 1–60 | A player who did not move for longer than this does not count as present |
| `attendance.graceMinutes` | `5` | 0–30 | Present at the start = within the radius and not idle at any time in the first this many minutes; present at the end = at any time in the last this many minutes. `0` = only the moment of the start and of the end |

Only players present at the start **and** at the end count as present: they get the attendance rewards and take part in the raffle. For a meeting at a vanilla warp, the warp's position is the meeting point.

---

## Log

In the admin window: **Rules** → **Log**.

| Option | Default | Range | Meaning |
|--------|---------|-------|---------|
| `history.keepDays` | `90` | 1–3650 | Days that finished and cancelled dates are kept, with their sign-ups, votes, results and rewards. Older ones are removed once an hour |

The **Results** tab of the events window always shows the last 30 days.

---

## What is set per event

These values are not in `config.json`. They belong to each event and are set on the **Plan** page:

| Setting | Notes |
|---------|-------|
| Kind | **Build contest** (needs KyuubiSoft Claims 2.0) or **Meeting point** |
| Name and description | Name 1–40 characters, description up to 300 |
| Date and time | In the server's time zone |
| Phase lengths | Contest: build, rating, ceremony. Meeting: duration |
| Repeat | Once, or every week on chosen weekdays; single dates can be skipped |
| Place | Meeting: your position (**Set here**) or a vanilla warp (**Pick warp**). Contest: optional |
| Build fields | Contest: one or more fields, in order |
| Theme | Contest: fixed, or empty for a random theme from the field's list |
| Raffle prizes | Meeting: 0–100 winners; 0 = no raffle |
| Reminders | Up to 5 times before the start |
| Rewards | Per slot up to 5 rewards (see below) |
| Season Pass XP ×2 | Off by default. Needs KyuubiSoft Season Pass |

### Rewards

| Slot | Kind of event |
|------|---------------|
| 1st place, 2nd place, 3rd place | Build contest |
| Participation | Build contest: everyone who got a plot |
| Everyone present | Meeting |
| Raffle | Meeting: each winner |

| Reward | What it gives | Needs |
|--------|---------------|-------|
| Item | An item id and an amount (1–10,000). What does not fit into the inventory waits in the window to be collected | KyuubiSoft Core |
| Coins | An amount of a currency; empty = the main currency | An economy through KyuubiSoft Core, for example [Kronen](https://wiki.kyuubisoft.com/hytale/core/kronen/) |
| Command | A command without `/`, run as the console; `{player}` becomes the player's name | KyuubiSoft Core, and `ks.core.admin.dialog.console` for the admin who adds it |
| Title | A hidden achievement of KyuubiSoft Achievements, by its id | KyuubiSoft Achievements |

Each reward can have a label that players see instead of the id ("Shown to players").

- Rewards that cannot be granted right now (the player is offline, or the needed mod is missing) wait for the player. Items are collected with **Collect** on the **Results** tab; titles, coins and commands are tried again at the next login.
- Coins wait while the player is offline, but they are not paid at all when no economy is connected.
- Each reward is given at most once per player and slot, also after a restart.

### Season Pass boost

With **Season Pass XP ×2 during the event** on, Events runs Season Pass's own admin command as the console when the event starts its first active phase: `ksseasonpassadmin doublexp <minutes>` with the minutes until the planned end (again after **+5 min**). When the event ends or is cancelled, it runs `ksseasonpassadmin stopdoublexp`. Season Pass has one boost for the whole server, so this replaces a boost that is already running.

---

## Languages

The texts of all windows, commands and messages are in `mods/kyuubisoft_events/localization/<area>/<language>.json` (areas `admin`, `core`, `integration`, `ui`; languages `en`, `de`, `es`, `fr`, `it`, `pl`, `pt-BR`, `ru`, `tr`). Missing files are written at the start. When a newer version brings newer texts, the file is replaced and your old one is kept as `<language>.json.backup-v<old version>`.

Each player's language comes from `/kslang`, which all KyuubiSoft mods share. Dates follow the language: `11/14` in English, `14.11.` in German.