# Quest Packs

# Quest Packs

Quest Packs are self-contained bundles of quests, chapters, NPC profiles and translations that can be shared between servers. They are the primary way to distribute community-created quest content.

## What Is a Quest Pack?

A quest pack is a single JSON file that contains everything needed for a set of quests to work:

- Quest definitions (side, daily, weekly, or story)
- Chapter structure (optional)
- NPC profiles (optional)
- Translations for EN and DE (optional)
- Metadata (name, author, description, color)

In the Questbook, pack quests are listed in the normal tabs by their type, most of them under **Side quests** (see [Quest Book Integration](#quest-book-integration)).

## Pack Structure

Every quest pack JSON file includes a `_pack_info` metadata block:

```json title="custom/halloween_event.json"
{
  "_pack_info": {
    "id": "halloween_2026",
    "name": "Halloween Event",
    "description": "Spooky quests for the Halloween season",
    "author": "ServerTeam",
    "version": "1.0.0",
    "createdAt": "2026-10-01",
    "updatedAt": "2026-10-15",
    "tags": ["event", "seasonal", "halloween"],
    "color": "#FF6600"
  },
  "quests": [
    {
      "id": "hw_collect_pumpkins",
      "type": "side",
      "category": "halloween_2026",
      "name": { "en-US": "Pumpkin Harvest", "de-DE": "Kuerbisernte" },
      "objectives": [
        { "id": "gather", "type": "items_collected", "targets": ["Pumpkin"], "count": 20 }
      ],
      "rewards": [
        { "type": "item", "itemId": "Candy_Bag", "amount": 1 }
      ]
    }
  ],
  "chapters": []
}
```

### `_pack_info` Fields

| Field | Required | Description |
|-------|----------|-------------|
| `id` | Yes | Unique identifier for the pack |
| `name` | Yes | Display name of the pack |
| `color` | No | Hex color of the pack (e.g. `#FF6600`) |
| `description` | No | Short description of the pack |
| `author` | No | Creator name |
| `version` | No | Semantic version string |
| `createdAt` | No | ISO date when the pack was created |
| `updatedAt` | No | ISO date of the last update |
| `tags` | No | Array of tags for categorization |

## Installing a Quest Pack

### Method 1: Drop the JSON file

1. Place the pack `.json` file into your server's `custom/` folder:
   ```
   mods/kyuubisoft_questbook/custom/halloween_event.json
   ```
2. Run `/ksquestadmin reload`
3. The pack's quests appear in the Questbook (see below), and in the admin window's quest list with the source "Pack"

:::tip
The file name (without `.json`) becomes the internal label. Choose a descriptive name like `halloween_event.json` rather than `pack1.json`.
:::

### Method 2: Import via command

1. Place the file in the `exports/` folder inside your quest data directory
2. Use `/ksquestadmin import <filename>` to import the quests
3. Imported quests are saved to the custom files and persist across restarts

## Quest Book Integration

Since the new Questbook (2.0.0) there are no separate pack tabs any more. Pack quests are sorted into the normal tabs by their type: daily, weekly and story quests go to their tabs, and every other quest (side quests and the usual pack quests) appears under **Side quests**. Story quests of a pack show in the Story tab when they belong to a chapter.

The admin window shows the pack as the quest's source, and its quest list can filter by source.

## The `.questpack` File Format

The Mod Editor uses a dedicated `.questpack` interchange format for sharing packs between editors. This format includes additional metadata not needed by the server:

```json
{
  "_editor_format": "questpack",
  "_editor_version": 1,
  "pack": { "id": "...", "name": "...", ... },
  "quests": [...],
  "chapters": [...],
  "npcProfiles": [...],
  "localeEN": { "quest.hw_collect_pumpkins.name": "Pumpkin Harvest", ... },
  "localeDE": { "quest.hw_collect_pumpkins.name": "Kuerbisernte", ... },
  "customReferences": { "items": ["Pumpkin", "Candy_Bag"], "entities": [], "blocks": [] }
}
```

:::info
The `.questpack` format is for editor-to-editor sharing. To install on a server, export from the Mod Editor as a server JSON file, or use the zip export which generates the correct `custom/` folder structure.
:::

## Creating Packs with the Mod Editor

The [Mod Editor](https://modeditor.kyuubisoft.com/) provides a dedicated Packs workflow. Create a pack, add quests/chapters/NPC profiles, set translations, then export as server JSON (for `custom/`), `.questpack` (for sharing with other editors), or ZIP (full deployment structure).

## Pack Conventions

- Use a unique ID prefix for all quests in a pack (e.g. `hw_` for Halloween) to avoid collisions
- Set `category` to match the pack ID so quests group correctly in the Quest Book
- Include EN translations at minimum; DE is recommended for multi-language servers

:::caution
If two packs contain quests with the same ID, the pack loaded last (alphabetically by filename) wins. Always use unique ID prefixes.
:::