# Rules Configuration

# Rules Configuration

**File:** `rules/rules.json`

Defines the server rules, organized in categories. The **Rules** tab of the book shows the categories with icon and count, every rule with a global number, a severity chip, a "changed" chip and the consequence line. The **Rules** board of the [admin window](./admin-panel#content-boards) edits this file.

## Complete Example

```json
{
  "settings": {
    "showRuleNumbers": true,
    "itemsPerPage": 5
  },
  "categories": [
    {
      "id": "general",
      "name": "General Rules",
      "description": "Basic behavior rules",
      "icon": "Deco_Book_Pile_Small",
      "rules": [
        {
          "title": "Be Respectful",
          "shortText": "Treat all players with respect.",
          "fullText": "Treat all players with respect. Insults, bullying, discrimination or harassment of any kind are strictly forbidden. We are a community where everyone should feel welcome.",
          "severity": "high",
          "consequence": "Warning -> Mute -> Ban"
        },
        {
          "title": "No Spam",
          "shortText": "Don't spam in chat or with commands.",
          "fullText": "Repeatedly sending the same or similar messages, excessive use of caps lock, or flooding the chat is forbidden.",
          "severity": "medium",
          "consequence": "Warning -> Mute"
        },
        {
          "title": "Language in Global Chat",
          "shortText": "Please use English or German in global chat.",
          "fullText": "In global chat, we ask you to use English or German so all players can understand the conversations. For other languages, please use private messages or group chats.",
          "severity": "low",
          "consequence": "Reminder"
        }
      ]
    },
    {
      "id": "gameplay",
      "name": "Gameplay Rules",
      "description": "Rules for fair play",
      "icon": "Weapon_Sword_Iron",
      "rules": [
        {
          "title": "No Cheating",
          "shortText": "Hacks and exploits are forbidden.",
          "fullText": "The use of hacks, cheats, exploits, modified clients or other unfair advantages is strictly forbidden. This includes X-Ray, fly hacks, speed hacks, aimbots and similar software.",
          "severity": "critical",
          "consequence": "Permanent Ban"
        },
        {
          "title": "No Griefing",
          "shortText": "Don't destroy other players' builds.",
          "fullText": "Intentionally destroying, damaging or defacing other players' builds without their permission is forbidden. This also applies to stealing items.",
          "severity": "high",
          "consequence": "Rollback + Ban"
        }
      ]
    }
  ]
}
```

---

## Settings

```json
{
  "settings": {
    "showRuleNumbers": true,
    "itemsPerPage": 5
  }
}
```

| Setting | Type | Default | Description |
|---------|------|---------|-------------|
| `showRuleNumbers` | Boolean | `true` | Show rule numbers in the list |
| `itemsPerPage` | Integer | `5` | Rules per page in the list view |

Category `permission` and `priority` are respected everywhere: browsing, search and counts.

---

## Category Structure

```json
{
  "id": "category-id",
  "name": "Category Name",
  "description": "Category description",
  "icon": "Item_Id",
  "permission": null,
  "priority": 1,
  "rules": []
}
```

| Field | Type | Description |
|-------|------|-------------|
| `id` | String | Unique category ID |
| `name` | String | Display name |
| `description` | String | Category description |
| `icon` | String | Item ID for icon |
| `permission` | String | Permission to view this category (null = everyone) |
| `priority` | Integer | Sort order (lower = higher, default: `99`) |
| `rules` | Array | Rules in this category |

---

## Rule Structure

```json
{
  "id": "rule-id",
  "title": "Rule Title",
  "shortText": "Short summary for the list.",
  "fullText": "Full description shown in detail view.",
  "severity": "high",
  "consequence": "Warning -> Ban",
  "icon": "Item_Id"
}
```

| Field | Type | Description |
|-------|------|-------------|
| `id` | String | Unique rule ID |
| `title` | String | Rule title (short and concise) |
| `shortText` | String | Short summary for list view |
| `fullText` | String | Full description for detail view |
| `description` | String | Alternative to `shortText`/`fullText` (used as fallback for both) |
| `severity` | String | Severity level |
| `consequence` | String | Consequence for violation |
| `icon` | String | Item ID for icon (optional) |
| `i18n` | Object | Optional title / texts / consequence per language, e.g. `{"de-DE": {"title": "..."}}` |

:::tip
If you only specify `description` (instead of `shortText` and `fullText`), it will be used for both.
:::

---

## Severity Levels

| Value | Chip in the book |
|-------|------------------|
| `low` (also `info`, `hint`, `minor`) | Notice |
| `medium` (default, also any unknown value) | Warning |
| `high` (also `major`, `severe`) | Mute / Kick |
| `critical` (also `ban`, `extreme`) | Ban |

---

## Rules acknowledgement

With `rules.requireAcknowledgement: true` in `config.json` (default **off**), players confirm the current rules in a window inside the book: a welcome text, the first five rules, "... and n more", a checkbox, **Read all rules** and **Confirm rules**.

- The confirmation is asked again when the text of a rule changes. Rules that changed since a player's confirmation are marked.
- Whitespace-only edits do not count as a change.
- Per-rule content hashes and change times are kept in `state/server_state.json`.
- In the admin window, **Correction only – no re-acknowledgement** (off by default) saves a typo fix without asking players again. New, removed or renamed rules always need re-acknowledgement.

The rules bar at the top of the Rules tab shows whether confirmation is due or when the player confirmed.

---

## Examples

### Simple Rule (Single Description)

```json
{
  "title": "Have Fun",
  "description": "This is a game - enjoy yourself and help others enjoy it too!",
  "severity": "info",
  "consequence": "None"
}
```

### PvP Rules Category

```json
{
  "id": "pvp",
  "name": "PvP Rules",
  "description": "Rules for player vs player combat",
  "icon": "Weapon_Sword_Iron",
  "rules": [
    {
      "title": "No Combat Logging",
      "shortText": "Don't disconnect during combat.",
      "fullText": "Disconnecting during PvP combat to avoid death is forbidden. You must wait at least 30 seconds after your last combat action before logging out.",
      "severity": "medium",
      "consequence": "Death + Warning"
    },
    {
      "title": "PvP Zones Only",
      "shortText": "PvP is only allowed in designated areas.",
      "fullText": "Player vs Player combat is only allowed in designated PvP zones. Attacking players in safe zones or spawn is forbidden.",
      "severity": "high",
      "consequence": "Warning -> Temp Ban"
    }
  ]
}
```

### Building Rules Category

```json
{
  "id": "building",
  "name": "Building Rules",
  "description": "Rules for construction and claims",
  "icon": "Tool_Pickaxe_Iron",
  "rules": [
    {
      "title": "Claim Your Builds",
      "shortText": "Protect your builds with claims.",
      "fullText": "We recommend claiming all your builds. Unclaimed builds are not protected and staff cannot help with grief recovery for unclaimed areas.",
      "severity": "info",
      "consequence": "N/A"
    },
    {
      "title": "No Inappropriate Builds",
      "shortText": "Keep builds family-friendly.",
      "fullText": "All builds must be appropriate for all ages. Offensive, explicit, or hate-related structures will be removed without warning.",
      "severity": "high",
      "consequence": "Removal + Ban"
    }
  ]
}
```

---

## Formatting Rule Text

### Color Codes

You can use Minecraft-style color codes in rule texts (`shortText`, `fullText`, `consequence`):

| Code | Color | Code | Color |
|------|-------|------|-------|
| `&0` | Black | `&8` | Dark Gray |
| `&1` | Dark Blue | `&9` | Blue |
| `&2` | Dark Green | `&a` | Green |
| `&3` | Dark Cyan | `&b` | Cyan |
| `&4` | Dark Red | `&c` | Red |
| `&5` | Purple | `&d` | Pink |
| `&6` | Gold | `&e` | Yellow |
| `&7` | Gray | `&f` | White |
| `&r` | Reset | | |

**Example with colors:**

```json
{
  "title": "No Cheating",
  "shortText": "Hacks and exploits are &cforbidden&r.",
  "fullText": "The use of &chacks&r, &ccheats&r, and &cexploits&r is strictly forbidden. Violators will receive a &4permanent ban&r.",
  "severity": "critical",
  "consequence": "&4Permanent Ban&r"
}
```

:::tip Text Wrapping
Rule texts automatically wrap to fit the display area. Long descriptions will be fully visible without truncation.
:::

---

## Best Practices

1. **Prioritize by importance** - Critical rules first
2. **Be specific about consequences** - "Ban" instead of "Punishment"
3. **Use `fullText` for details** - Short list, detailed view
4. **Group logically** - Related rules in same category
5. **Keep titles short** - Easy to scan in lists
6. **Use colors sparingly** - Highlight key terms only