# Getting Started

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

## 1. Install the mod

1. Stop the server.
2. Put `KyuubiSoftGuilds-1.0.0.jar` into the server's `mods/` folder.
3. Optional: add the KyuubiSoft mods you want Guilds to work with (see [the list on the start page](https://wiki.kyuubisoft.com/hytale/guilds/#optional-kyuubisoft-mods)).
4. Start the server.

```
mods/
  KyuubiSoftGuilds-1.0.0.jar
```

No other mod is needed. The textures of the windows are inside the jar.

---

## 2. Files after the first start

```
mods/
  kyuubisoft_guilds/
    config.json           all settings (see Configuration)
    players.json          known player names and personal settings
    feed.json             recent events for the admin overview
    crossmod.json         what the guild objectives already counted (with Quests or Achievements)
    guilds/<id>.json      one file per guild
    locks/<world>.json    the locks of one world
    lager/<id>.json       the storage of one guild
    lager/archive/        storages of guilds an admin disbanded
    placed-ores/          ore blocks that players placed (they earn no experience)
    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.

Guilds keeps its data in memory and writes changed files every 60 seconds and when the server stops. Each file is written to a temporary file first and then moved into place.

The log shows lines like these during the start:

```
[Guilds] Loaded 9 language(s), ...
[Guilds] Ready, command /ksguild
[Guilds] Links: none (own chat tag, no currency)
```

The `Links` line names the KyuubiSoft mods that were found, for example `Core, admin hub, Nameplates`.

---

## 3. First steps for players

### Found a guild

1. Type `/ksguild`. Without a guild the window opens on **Found a guild**.
2. Type the **name of the guild** (3 to 24 characters) and a **tag** (2 to 4 letters or digits, written in capitals). The line below says whether both are still free.
3. Pick a **colour**, a **coat of arms** and how players join: **Open**, **On request** or **Invite only**. The right side shows how the crest, the chat line and the name tag will look.
4. Click **Found the guild**. You take the rank Leader.

In chat it works too, with the tag first: `/ksguild create NW The Night Watch`. A guild founded this way starts with the colour Blue, the Moon crest and joining **On request**; change them later on the **Settings** tab.

Founding is free unless the admin set a founding fee and a currency is connected.

### Invite players

1. On the **Members** tab, click **Invite**.
2. Type a name, or pick one of the players under **Online without a guild**, and click **Invite**.

In chat: `/ksguild invite <player>`. The invitation is valid for 10 minutes. The invited player gets a card at the top of the screen and accepts it in their guild window or with `/ksguild accept`. Players who are offline see open invitations when they log in.

Players who want to join a guild **On request** send a request from **All guilds** or with `/ksguild join <guild>`. Members with the right to accept requests see them on the **Members** tab and click **Accept** or **Decline**.

### Ranks

- New members start as **Novice**.
- Select a member on the **Members** tab to **Promote to ...**, **Demote**, **Hand over the lead** or **Remove** them. You can only act on ranks below your own, and only promote up to below your own rank.
- On the **Ranks** tab the leader renames the ranks (**Save names**) and ticks what each rank may do. The leader always has every right.

Default rights of a new guild:

| Right | Officer | Veteran | Member | Novice |
|-------|:-------:|:-------:|:------:|:------:|
| Invite members | yes | yes | yes | |
| Accept join requests | yes | yes | | |
| Remove lower ranks | yes | | | |
| Promote and demote, up to below their own rank | yes | | | |
| Write the announcement | yes | | | |
| Lock chests and doors for the guild | yes | yes | yes | |
| Change and remove other members' guild locks | yes | | | |
| Put items into the guild storage | yes | yes | yes | yes |
| Take items from the guild storage | yes | yes | yes | |
| Travel to the guild home | yes | yes | yes | yes |
| Set the guild home | | | | |
| Manage guild land | | | | |

The Veteran rank only exists from guild level 6. The admin can change these defaults for new guilds in `config.json` (`defaultRights`).

### Lock a chest

1. Stand within 10 blocks of a chest, barrel, cupboard, door or gate and look at it.
2. Type `/ksguild lock`. The lock window opens.
3. Choose **Only me** or your guild. For the guild, pick the lowest rank that may open it (**Opens from rank**).
4. Optional: add single players under **Also allow**.
5. Click **Lock**.

To change or remove the lock later, look at it and type `/ksguild lock` again, or click its row on the **Locks** tab. `/ksguild unlock` removes it, `/ksguild lockinfo` shows who owns it.

To lock new chests and doors right when you place them, use `/ksguild autolock guild` (or `private`), the **Lock automatically** button on the **Locks** tab, or **Lock new chests and doors** on the **Settings** tab.

### Use the guild storage

1. Open the **Storage** tab.
2. Click or drag items between the storage page and your inventory below. One click moves the whole stack.

The box **Your rights** says what your rank may do and how much you may still take out today. Only one person at a time can change a page; others can look at it meanwhile. The **Log** lists who put in or took out what.

A new guild has one page. More pages come with higher levels.

### Set and use the guild home

The guild home is unlocked at **level 2**, the second one at **level 7**.

1. Stand on solid ground with two blocks of air above you. Instance worlds do not work.
2. Type `/ksguild sethome` (or `/ksguild sethome 2` for the second home), or click **Set here** on the **Settings** tab. By default only the leader may set the home.
3. Members travel with **To the guild home** in the window or `/ksguild home` (`/ksguild home 2`).

The trip starts after 5 seconds of standing still. Moving more than one block or taking damage cancels it. After a trip you wait 10 minutes for the next one.

### Raise the guild level

- Members earn experience for the guild by playing; see [How is experience earned?](./faq#how-is-experience-earned).
- From level 3 a level also needs building materials. On the **Level** tab, click **Hand in from inventory**, or type `/ksguild contribute`. Only what is still missing is taken from your inventory; the rest stays with you.

---

## 4. First steps for admins

1. **Give yourself the admin node.** Add `ks.guilds.admin` to your player or staff group. See [Permissions](./permissions).
2. **Open the admin window.** Type `/ksguild admin`, or click the **Guilds** tile in the `/ksadmin` hub if KyuubiSoft Core is installed.
3. **Check what is connected.** The **Overview** lists the optional KyuubiSoft mods and whether each one is connected right now.
4. **Check the rules.** On **Rules** you find name and tag lengths, how long invitations last, the founding fee, the guild home, what can be locked and the storage limits per rank. Changes apply at once and are written to `config.json`.
5. **Check the word filter.** On **Names** you add forbidden words and reserved tags, and test a name and tag as when founding.
6. **Check the levels.** On **Levels** you edit the level table, the experience values and the limits against farming, or switch the level system off.

Admins who should open locked chests and doors of other players also need `ks.guilds.admin.bypass`.

---

## Next steps

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