# Getting Started

**Version:** 1.0.0 (not released yet, not tested in game)

## 1. Install the mod

1. Stop the server.
2. Put `KyuubiSoftEvents-1.0.0.jar` into the server's `mods/` folder.
3. For build contests, also install KyuubiSoft Claims 2.0.0 or newer. Optional: add the other KyuubiSoft mods you want Events to work with (see [the list on the start page](https://wiki.kyuubisoft.com/hytale/events/#optional-kyuubisoft-mods)).
4. Start the server.

```
mods/
  KyuubiSoftEvents-1.0.0.jar
```

The textures of the windows are inside the jar.

---

## 2. Files after the first start

```
mods/
  kyuubisoft_events/
    config.json                   all settings (see Configuration)
    events.json                   the planned events and the templates
    fields.json                   the build fields: plot sizes, locked plots, themes, state of the empty-state snapshot
    players.json                  reminder settings, "Remind me" marks, return points, rewards waiting, known names
    runs/<run id>.json            one file per date that took place or is planned: sign-ups, plots, votes, result, attendance, raffle, rewards, log
    snapshots/<field id>.snapshot.gz   the saved empty state of a build field
    localization/                 language files, one folder per area
  kslang/                         language choice shared by all KyuubiSoft mods
```

Some files and folders only appear once they have something to store.

Events keeps its data in memory and writes changed files every 60 seconds, after a ceremony or the end of a meeting, and when the server stops. Each file is written to a temporary file first and then moved into place. A file that cannot be read is kept as `<name>.broken`.

The log shows lines like these during the start:

```
[Events] Loaded 9 language(s), en has 1009 keys
[Events] Loaded 0 event(s), 0 field(s), 0 run(s), 0 player(s)
[Events] Ready, commands /ksevent and /kseventadmin
[Events] World: Claims connected, build veto on, field snapshots ready
[Events] Links: Core, admin hub, KS settings, toast lane, currency, Whisperstone (tile), Season Pass, Achievements (trowel titles)
```

The `World` line says whether build contests are possible (`Claims missing (build contests off)` without Claims). The `Links` line names the KyuubiSoft mods that were found; without any it says `none (chat lines only, rewards wait)`.

---

## 3. First steps for players

### Look at the calendar

1. Type `/ksevent` (or `/events`). The window opens on **Calendar**.
2. The week strip shows every date of the week. **‹** and **›** switch weeks, **Today** comes back.
3. **Coming up** lists the dates of the next 14 days. Click one to see its details on the right: time, place, schedule, rewards.

In chat, `/ksevent list` shows the same dates with numbers.

### Join or get reminded

- **Join** signs you up. For a build contest you get your plot at the start; you can still join until 10 minutes after the start while plots are free.
- **Leave** takes it back. In a contest, leaving is closed during the voting and the ceremony.
- **Remind me** only marks the date for the reminders, without signing up.
- The bar **Reminders** at the bottom left decides which dates remind you by themselves: **All events**, **Only events I joined** (default) or **Off**. A date you marked with **Remind me** always reminds you.

In chat: `/ksevent join 2`, `/ksevent leave 2`, `/ksevent remind 2` (mark one date) and `/ksevent remind all|joined|off`.

### Travel there

From 10 minutes before the start until the end:

1. Click **Travel there** in the window (on **Now**: **To my plot** in a contest), or type `/ksevent travel`.
2. Stand still for 3 seconds. Moving more than one block or taking damage cancels the trip.
3. You land on your own plot (contest) or at the meeting point.

**Back where I was** (or `/ksevent back`) takes you back to where you were before the first trip, until 30 minutes after the end. You cannot travel from a dungeon or minigame.

### Build

- At the start, a card at the top of the screen names the theme, and a chat line tells you your plot.
- You can only build on your own plot, and only during the build time. The card at the left edge shows the time left.

### Rate

When the build time is over, the voting starts.

1. Type `/ksevent vote`, or click **Rate** on the **Now** tab. A bar opens at the bottom of the screen.
2. Walk onto a plot, or click **Next plot** to be taken to the next plot you have not rated.
3. Click one of the five diamonds. The rating is saved at once; you can change it until the voting ends.

You can rate if you signed up or if you are on the field during the voting. You never rate your own plot.

### See the results

The **Results** tab lists the events of the last 30 days: the podium, all places, your own place and what you received. Items that did not fit into your inventory wait there; click **Collect**.

---

## 4. First steps for admins

1. **Give yourself the admin node.** Add `ks.events.admin` to your player or staff group. See [Permissions](./permissions).
2. **Open the admin window.** Type `/kseventadmin`, or click the **Events** tile in the `/ksadmin` hub if KyuubiSoft Core is installed.
3. **Check the rules.** On **Rules** you set the time zone, the reminder times and channels, travel and attendance. See [Configuration](./configuration).

### Set up a build field (for build contests)

Build contests need KyuubiSoft Claims 2.0.0 or newer.

1. In Claims, create a **server zone** that covers the area for the contest (whole chunks, for example 4 × 3 chunks = 128 × 96 blocks). Leave its build rule off; Events switches it on during the build time.
2. Stand on the ground of that area, in the same world.
3. In the admin window, open **Build field**, click **New build field** and pick the zone. Confirm: the empty state is taken from your height, 4 blocks down and 60 blocks up.
4. Set **Plot size** and **Path between** and click **Apply**. The preview shows the plots; click a free plot to lock it.
5. Click **Save empty state** while the area is still empty. Only with a saved empty state can the field be reset before the next contest. You can also type `/kseventadmin field snapshot <field>`.
6. Add **Themes**. Contests without a fixed theme draw one from this list.

To test the reset on a small area first, run `/kseventadmin field selftest` (also from the console) and read the result in the server log.

### Plan an event

1. Open **Plan**. Choose **Build contest** or **Meeting point** and give it a name (up to 40 characters) and an optional description (up to 300 characters).
2. Set date, time and the lengths of the phases (contest) or the duration (meeting).
3. Under **Repeat**, click weekdays for a weekly event. **Skip dates** leaves out single dates.
4. Contest: **Pick fields** chooses the build fields, in order; when one cannot be reset, the next is used. **Theme** stays empty for a random theme from the field's list. Meeting: **Set here** takes your position, **Pick warp** a vanilla warp.
5. Optional: reminder times, **Add reward** per place or for everyone present, and **Season Pass XP ×2 during the event**.
6. Click **Save**. Players see the date in their calendar at once.

**Templates** at the right fill the form: the built-in **Build contest** (Saturdays 20:00, 60 / 20 / 5 minutes) or your own (**Save as template**). **Plan it** loads a template into the form.

### During an event

The **Overview** shows the running event with **Next phase**, **+5 min**, **End** and **Cancel …**, the participants with **remove**, and suspicious votes to check. The same works in chat with `/kseventadmin next`, `extend`, `end` and `cancel`, also from the console. See [Commands](./commands).

A build contest with fewer than 2 sign-ups at its start is cancelled, and everyone who joined is told. Meetings always take place.

---

## Next steps

- [Commands](./commands) for the full syntax
- [Configuration](./configuration) for every option
- [UI Pages](./ui-pages) for what players and admins see