# Getting Started

**Version:** 2.0.0 (not released yet)

## 1. Install the plugin

1. Stop the server.
2. Put `KyuubiSoftClaims-2.0.0.jar` into the server's `mods/` folder. When you update, remove the old `KyuubiSoftClaims-*.jar` first.
3. Optional: KyuubiSoft Core (admin hub tile, shared card row, economy), KyuubiSoft Guilds (guild land), KyuubiSoft Player Shops (claim check for shops). See [Requirements](https://wiki.kyuubisoft.com/hytale/claims/#requirements).
4. Start the server.

```
mods/
  KyuubiSoftClaims-2.0.0.jar
```

No other mod is needed.

---

## 2. Files after the first start

```
mods/
  kyuubisoft_claims/
    config.json             main configuration
    localization/           texts per area and language (core, protect, ui, admin, integration)
    claims/                 one file per claim
    zones.json              server zones
    players.json            quota, play time and known player names
    logs/                   the log of each claim
  kslang/                   language choice shared by all KyuubiSoft mods
```

- `config.json` and `localization/` are written at the first start. The other files appear as soon as there is something to save. Claims keeps everything in memory and saves changes every 60 seconds and when the server stops.
- A file that cannot be read is kept as `<name>.broken` before it is replaced.

During the start the log shows:

```
[Claims] Ready, commands /ksclaim and /ksclaimadmin
[Claims] Links: Core on, economy off, showcase openers on, admin hub on
```

The second line tells you what Claims found. Without KyuubiSoft Core every entry reads `off`. `economy` is only `on` when `economy.enabled` is `true` in `config.json` and Core's economy bridge has a currency.

---

## 3. Coming from an older Claims version

When the data folder holds a `claims.db` from an older Claims version and there are no 2.0 claims yet, Claims converts it on the first start:

- **Taken over:** claims (with the same IDs), their chunks, members, bans and homes, admin regions (they become [server zones](./rights-and-roles#server-zones)), each player's bonus chunks, bought chunks and play time, the known player names, and the last 30 days of the log.
- **Rectangle areas** become every chunk they touch. Where two claims overlap, server zones win first, then the older claim. Every conflict is listed in the report.
- **Roles:** trusted members become **Trusted**, co-owners become **Co-owner**. Visitor members are dropped.
- **Not taken over:** permanent admin overrides. Chunks taken over are not in the cost book, so releasing them refunds nothing.
- **Afterwards:** `claims.db` is renamed to `claims-1.x.db` and `migration-report.txt` lists the numbers and every conflict. The overview of the admin window shows the numbers for this start too.

The log shows:

```
[Claims] Found a Claims 1.x database, migrating ...
[Claims] Migration done: 42 claims, 610 chunks, 1 conflicts (see migration-report.txt)
```

If the conversion fails, the log says `[Claims] Migration from 1.x failed, the old database stays untouched`. Nothing is half-converted, and the next start tries again.

An old `config.json` is kept as `config-1.x.json`. Its values are taken over where the feature still exists: start and maximum chunks, claims per player, locked worlds, the use exceptions, the prices, the home cooldown and abandoned claims if they were switched on. Growth with play time stays off.

The permission nodes and commands changed as well: the old `ks.claim.user.use`, `ks.claim.admin` and `ksclaim.admin` are no longer checked, and the short forms `/ksc` and `/ksca` are gone. See [Permissions](./permissions).

---

## 4. Your first claim

1. **Open the window.** Stand on free land and type `/ksclaim`. The window opens on the **Map** tab. The map shows 19 × 15 chunks around you, and your chunk is marked as **You**.
2. **Pick chunks.** Keep the mode on **Claim** and click free chunks. They must be connected, up to 64 at once. The panel under the map says what happens, for example `Then 9 of 25 used. A new claim is made.`
3. **Claim them.** Click **Claim**. The new claim is called after you, for example `Mira's Land`. A notice at the top confirms it.
4. **Rename it.** On the **Settings** tab type a name (3 to 24 characters) and click **Save**, or stand in the claim and type `/ksclaim rename Sunny Farm`.
5. **Grow it.** Claim chunks that touch it. If the chunks touch two of your claims, the window asks which one should grow. Chunks that touch none of your claims start a new claim.

Without the window: `/ksclaim claim` claims the chunk you stand in, `/ksclaim claim <name>` gives a new claim a name or names the claim that should grow.

### Show the border

Stand in the claim and click **Show border** in the left column, or type `/ksclaim border`. Golden light pillars glow along the edge for 10 seconds. Only you see them, and only the part within 64 blocks of you.

### Set a home

Stand in your claim where the home should be and click **Set home here** (or type `/ksclaim sethome`). The home keeps the direction you are looking. **Travel home** (or `/ksclaim home`) takes you there: stand still for 3 seconds, then you travel. Moving, getting hurt or changing worlds cancels the trip.

---

## 5. Trusting people

1. Open the **Rights** tab. On the right is **People**.
2. Type a player name into **Add player** and click **Add**. The player becomes **Trusted** and gets a notice.
3. Click the role of a person to switch between **Trusted** and **Co-owner**. Only the owner can do this. **×** takes the role away.
4. **Ban** next to **Add** bans the player instead. Banned players cannot enter the claim and are pushed back to its edge.

The same with commands, standing in the claim:

```
/ksclaim trust Mira               Mira becomes Trusted
/ksclaim trust Mira coowner       Mira becomes Co-owner
/ksclaim untrust Mira             Mira has no role any more
/ksclaim ban Tom                  Tom may not enter
/ksclaim unban Tom                lifts the ban
```

What each role may do is set in the table on the left of the **Rights** tab. The defaults:

| Role | May by default |
|------|----------------|
| Visitor (everyone without a role) | pick up items, drop items, sit on seats |
| Trusted | everything except hurting animals and managing |
| Co-owner | everything |
| Owner | always everything |

Click a checkbox to change it. See [Rights and Roles](./rights-and-roles) for every right.

---

## 6. A zone with its own rules

1. On the **Map** tab switch the mode to **Pick zone** and click chunks of your claim.
2. Click **Create zone** and give the zone a name.
3. The **Zones** tab opens with the rules of the zone. Each cell shows **like the claim**, **allowed** or **forbidden** for visitors and trusted players. A click switches to the next state.

Example: a shop where visitors may open the doors. In the shop zone, click the **Visitors** cell of **Doors and gates** once, so it reads **allowed**. Everywhere else in the claim, visitors still cannot open doors.

---

## 7. First steps for an admin

1. **Grant yourself `ks.claims.admin`.** It opens `/ksclaimadmin` and the admin window.
2. **Open the admin window.** Type `/ksclaimadmin`, or click the Claims tile in the `/ksadmin` hub if KyuubiSoft Core is installed.
3. **Protect the spawn.** Stand in the middle of the spawn and type:
   ```
   /ksclaimadmin zone create Spawn 3
   ```
   This makes a server zone of 7 × 7 chunks around you (radius 3). Chunks that are claimed already stay with their owners. Instead, on the **Server zones** page use **New zone from a map selection** and click the chunks. A new server zone lets everyone enter and use doors and benches, but nobody builds, opens containers, fights or blows things up there. Click a rule to change it.
4. **Check the rules.** The **Rules and protection** page has the quota, abandoned claims, the economy, the worlds where claiming is allowed, the protection switches, the messages and the home timers. Changes apply right away and are written to `config.json`.
5. **Step in when needed.** `/ksclaimadmin bypass` lets you ignore every claim until you log out. A note next to the compass reminds you that it is on. Admins who should always ignore the protection get `ks.claims.admin.bypass`.

All admin commands are on [Commands](./commands#admin-commands).

---

## 8. Languages

Claims comes in nine languages: English, German, Spanish, French, Italian, Polish, Portuguese (Brazil), Russian and Turkish. Every window, notice and chat line is shown in the player's language.

- Players choose their language with `/kslang <code>`, for example `/kslang de-DE`. `/kslang` alone shows the current language and the codes, `/kslang auto` follows the game language. The choice is shared by all KyuubiSoft mods.
- The texts are in `mods/kyuubisoft_claims/localization/<area>/<language>.json` and can be edited. `/ksclaimadmin reload` reads them again.
- When a new version brings newer texts, the file is replaced and your old one is kept as `<language>.json.backup-v<old version>`. Keys missing in your file always come from the jar.

---

## Next steps

- [Commands](./commands) for the full syntax
- [Rights and Roles](./rights-and-roles) for what every right covers
- [Configuration](./configuration) for every option
- [UI Pages](./ui-pages) for the windows