# Guilds

**KyuubiSoft Guilds lets players found a guild, invite others and give each rank its own rights. Members lock chests and doors for themselves or for the guild, fill a shared guild storage and travel to a guild home. Together they earn experience and hand in building materials to raise the guild through ten levels, which unlock more members, storage pages, locks, a second home and new crests. Admins manage every guild, the level table and all rules in one window.**

:::caution[Not tested in game yet]
Version 1.0.0 is not released yet. It was built against Hytale 0.7.6, but it has not been tested in game. Windows, texts and numbers can still change before the release.
:::

---

## How it works

- **One guild per player.** A player founds a guild with a name, a short tag, a colour and a crest, or joins one that exists. Nobody can be in two guilds at once.
- **Joining.** Each guild decides who may join: **Open** (anyone joins at once), **On request** (a member with the right accepts the request) or **Invite only**. Invitations are valid for 10 minutes.
- **Ranks.** Five ranks: Leader, Officer, Veteran, Member and Novice. Veteran is only active from level 6. New members start as Novice. The leader sets with checkboxes what each rank may do and can rename the ranks.
- **Locks.** A player looks at a chest, barrel, cupboard, door or gate and types `/ksguild lock`. The lock is private (only the owner plus extra players) or belongs to the guild (members from a chosen rank). Strangers cannot open, carry away, break or blow up a locked block.
- **Levels.** Members earn experience for the guild by defeating creatures, mining ores and playing (plus quests and achievements with those KyuubiSoft mods). From level 3 a level also needs building materials that members hand in. A guild never loses a level.
- **Storage and home.** The guild storage has up to six pages, unlocked by level. The guild home is unlocked at level 2, a second one at level 7.
- **Data.** Everything is stored in JSON files in the mod's data folder. No database is needed.

---

## Features

### Guilds and members

- `/ksguild` opens the guild window. Without a guild it shows **Found a guild** and **All guilds**.
- Found a guild in the window with a live check of name and tag and a preview of the crest, the chat line and the name tag, or with `/ksguild create <TAG> <name>`.
- Invite players by name or pick them from a list of online players without a guild. Accept invitations and join requests in the window or with `/ksguild accept`.
- Promote, demote, remove members and hand over the leadership in the window, with a confirmation step for the risky actions.
- An announcement of up to 200 characters for all members.

### Ranks and rights

- Twelve rights per rank: invite, accept requests, remove lower ranks, promote and demote, write the announcement, lock for the guild, manage other members' guild locks, put into the storage, take from the storage, travel home, set the home and manage guild land.
- Promotions only go up to below the own rank. The leader always has every right.

### Locks on chests and doors

- Lock what you look at with `/ksguild lock`. A lock window opens where you choose private or guild, the lowest rank that may open it and extra players.
- A locked block is protected against opening, carrying, breaking, damage and explosions. The block below it is protected too, and strangers cannot put a second chest next to a locked chest or a second door next to a locked door.
- A workbench that has a locked chest in its reach can only be used, or set down there, by players who may open that chest. So nobody takes material out of it through the bench.
- New chests and doors can be locked automatically when you place them (`/ksguild autolock`).
- All guild locks and your own private locks are listed in the window and can be changed from afar.
- Limits: guild locks by level (50 at level 1), 50 private locks per player.

### Guild levels

- Ten levels. Each needs a total of experience, and from level 3 also building materials.
- Experience comes from creatures the world spawned, bosses, ores nobody placed, play time with movement, finished quests and unlocked achievements.
- A daily limit per member (500), a 24-hour wait for new members and a farm brake keep it fair.
- Levels unlock more member slots, storage pages and guild locks, the guild home, the Veteran rank, more colours and crest symbols, crest frames and the hall of fame.

### Guild storage

- Up to six pages with 36 slots each. Put items in and take them out by click or drag.
- Each rank has its own rights and a daily limit for taking items out.
- A log shows who put in or took what, for 30 days.

### Guild home

- Up to two homes. Travel there after a warm-up of 5 seconds; moving or taking damage cancels the trip. After a trip there is a cooldown of 10 minutes.

### Chat and tag

- The guild tag stands in front of your name in the chat, in the guild colour.
- `/gc <text>` writes to your guild. `/gc` alone switches your chat to the guild and back.

### No harm among members

- Guild members cannot hurt each other, also not with arrows. Each guild can switch this off.

### Chronicle and ranking

- The guild remembers its last 100 events.
- The list of all guilds is ranked by level.

### Admin window

- `/ksguild admin` (needs `ks.guilds.admin`): an overview with the latest events and the connected mods, every guild with tools to step in, the level table, all rules, all locks and a word filter for names.

### Languages

- 9 languages: en, de, es, fr, it, pl, pt-BR, ru, tr. Each player can pick a language with `/kslang`, which all KyuubiSoft mods share.

---

## Requirements

- Hytale server 0.7.x (built against 0.7.6) and Java 25.
- No other mod is required.

### Optional KyuubiSoft mods

Guilds works without any of them. When one is installed, the matching part is added; the admin overview shows what is connected right now.

| Mod | What it adds |
|-----|--------------|
| [Core](https://wiki.kyuubisoft.com/hytale/core/) | A **Guilds** tile in the `/ksadmin` hub, a currency for the founding fee, and guild cards in Core's shared card row at the top of the screen |
| [Claims](https://wiki.kyuubisoft.com/hytale/claims/) 2.0.0 or newer | Guild land: a claim of your own becomes land of the guild, members from a chosen rank may build and use blocks there. Adds the **Guild land** tab and `/ksguild land`. Inside claims, only players who may use a block there can lock it |
| [VoiceHub](https://wiki.kyuubisoft.com/hytale/voicehub/) 2.0.3 or newer | A voice channel per guild, only for its members |
| [Quests](https://wiki.kyuubisoft.com/hytale/quest-system/) | Guild experience for finished quests. From 2.1.9: guild objective types for your own quests |
| [Achievements](https://wiki.kyuubisoft.com/hytale/achievement-system/) | Guild experience for unlocked achievements. From 3.1.7: guild trigger types for your own achievements |
| [Nameplates](https://wiki.kyuubisoft.com/hytale/nameplates/) | The guild tag above the head |
| ChatPlus | The guild tag as a chat prefix through ChatPlus. Without it the tag shows anyway |
| [Whisperstone](https://wiki.kyuubisoft.com/hytale/whisperstone/) | An invitation also reaches players who are offline, as a message on their whisper stone |
| [Order Board](https://wiki.kyuubisoft.com/hytale/orders/) | Guild orders: only members of the guild see and fill them. They close with a refund when the member who posted them leaves the guild |

---

## Where to go

| Page | Read it for |
|------|-------------|
| [Getting Started](./getting-started) | Installing, the files, first steps for players and admins |
| [Commands](./commands) | Every command with syntax and permission |
| [Permissions](./permissions) | The permission nodes and what the guild ranks decide instead |
| [Configuration](./configuration) | Every option of `config.json`, the level table, anti-farm settings |
| [UI Pages](./ui-pages) | The guild window, the lock window, the storage, the cards and the admin window |
| [FAQ](./faq) | Common questions about locks, levels, disbanding and other mods |
| [Changelog](./changelog) | What changed in each version |

---

## Quick Reference

| Item | Details |
|------|---------|
| **Plugin** | KyuubiSoft Guilds (manifest `kyuubisoft:guilds`) |
| **Version** | 1.0.0 (not released yet) |
| **Jar** | `KyuubiSoftGuilds-1.0.0.jar` |
| **Main command** | `/ksguild` (aliases `/guild`, `/gilde`) |
| **Guild chat** | `/gc` |
| **Permissions** | `ks.guilds.user.<action>` (players, allowed by default), `ks.guilds.admin`, `ks.guilds.admin.bypass` |
| **Data folder** | `mods/kyuubisoft_guilds/` |
| **Config** | `mods/kyuubisoft_guilds/config.json` |
| **Required** | nothing else |
| **Optional** | KyuubiSoft Core, Claims, VoiceHub, Quests, Achievements, Nameplates, ChatPlus, Whisperstone |