# 📖 Quest System - Complete Documentation

**SkyzerFusionCore Quest System**

**Generated:** Thu Feb 12 16:18:10 CET 2026

This is a comprehensive guide to creating and managing quests in SkyzerFusionCore.

---

## 📋 Table of Contents

1. [Overview](#overview)
2. [File Structure](#file-structure)
3. [Quest Format](#quest-format)
4. [Task Types](#task-types)
5. [Rewards System](#rewards-system)
6. [Dependencies](#dependencies)
7. [Unlocks System](#unlocks-system)
8. [Complete Examples](#complete-examples)
9. [Best Practices](#best-practices)
10. [Troubleshooting](#troubleshooting)

---

## 1. Overview

The Quest System is a JSON-based progression system with:

- **15 Task Types** - Craft, Collect, Kill, Visit, and more
- **3 Reward Types** - Guaranteed, Random, Choice
- **Dependency System** - Chain quests together
- **Progressive Unlocks** - Lock items, recipes, dimensions, JEI categories
- **Chapter Organization** - Group quests into chapters

---

## 2. File Structure

```
config/skyzer/quests/
└── chapters/
    ├── 01_getting_started.json
    ├── 02_basic_tech.json
    ├── 03_basic_magic.json
    └── ...
```

Each JSON file can contain one quest. The file name doesn't matter.

---

## 3. Quest Format

### Minimal Quest Example

```json
{
  "questId": "my_first_quest",
  "chapterId": "01_getting_started",
  "title": "My First Quest",
  "description": "A simple quest to get started",
  "tasks": [
    {
      "taskId": "task1",
      "type": "COLLECT",
      "item": "minecraft:dirt",
      "count": 10
    }
  ]
}
```

### Complete Quest Structure

```json
{
  // === REQUIRED FIELDS ===
  "questId": "unique_quest_id",          // Must be unique across all quests
  "chapterId": "chapter_identifier",      // Groups quests together
  "title": "Quest Display Name",          // Shown in quest book

  // === OPTIONAL FIELDS ===
  "description": "Detailed description",  // Quest details
  "icon": "minecraft:diamond",            // Item ID for quest icon

  "position": {                           // Position in quest tree GUI
    "x": 100,
    "y": 50
  },

  "dependencies": { ... },                // See Dependencies section
  "tasks": [ ... ],                       // See Task Types section
  "rewards": { ... },                     // See Rewards section
  "unlock": { ... },                      // See Unlocks section
  "metadata": { ... }                     // See Metadata section
}
```

---

## 4. Task Types

### Available Task Types

| Type | Description | Required Fields |
|------|-------------|----------------|
| `CRAFT` | Craft X items | `item`, `count` |
| `COLLECT` | Have X items in inventory | `item`, `count` |
| `KILL` | Kill X mobs (any type) | `count` |
| `KILL_SPECIFIC` | Kill specific entity | `entity`, `count` |
| `VISIT_DIMENSION` | Travel to dimension | `target` (dimension ID) |
| `VISIT_BIOME` | Find biome | `target` (biome ID) |
| `ADVANCEMENT` | Trigger advancement | `target` (advancement ID) |
| `OBSERVATION` | Stay near block/entity | `target`, `count` (seconds) |
| `USE_ITEM` | Use item X times | `item`, `count` |
| `BREAK_BLOCK` | Mine X blocks | `target`, `count` |
| `PLACE_BLOCK` | Place X blocks | `target`, `count` |
| `INTERACT` | Interact with block/entity | `target`, `count` |
| `CONSUME` | Eat/drink items | `item`, `count` |
| `EXPERIENCE` | Reach XP level | `count` (level) |
| `CUSTOM_TRIGGER` | Custom event via API | `target` (event ID) |

### Task Examples

```json
// CRAFT task
{
  "taskId": "craft_pickaxe",
  "type": "CRAFT",
  "item": "minecraft:diamond_pickaxe",
  "count": 1,
  "consume": false  // Don't consume on completion
}

// VISIT_DIMENSION task
{
  "taskId": "visit_nether",
  "type": "VISIT_DIMENSION",
  "target": "-1",  // Nether dimension ID
  "count": 1
}

// KILL_SPECIFIC task
{
  "taskId": "kill_ender_dragon",
  "type": "KILL_SPECIFIC",
  "entity": "minecraft:ender_dragon",
  "count": 1
}
```

---

## 5. Rewards System

### Reward Types

**1. Guaranteed Rewards** - Always given

```json
"rewards": {
  "guaranteed": [
    {"type": "item", "item": "minecraft:diamond", "amount": 5},
    {"type": "xp", "amount": 500},
    {"type": "aether", "amount": 250},
    {"type": "skill_points", "amount": 1},
    {"type": "home_slot", "amount": 1}
  ]
}
```

**2. Random Rewards** - Weighted random selection

```json
"rewards": {
  "random": {
    "rolls": 2,  // Number of rewards to give
    "pool": [
      {"item": "minecraft:diamond", "count": "1-3", "weight": 5},
      {"item": "minecraft:emerald", "count": "2-5", "weight": 10}
    ]
  }
}
```

**3. Choice Rewards** - Player selects one option

```json
"rewards": {
  "choice": {
    "choose": 1,  // How many to choose
    "options": [
      {"type": "home_slot", "description": "+1 Home Slot"},
      {"type": "aether", "amount": 500, "description": "500 Æther"}
    ]
  }
}
```

### Available Reward Types

| Type | Description | Fields |
|------|-------------|--------|
| `item` | Give ItemStack | `item`, `amount` |
| `xp` | Give XP points | `amount` |
| `aether` | Give Æther energy | `amount` |
| `skill_points` | Give skill points | `amount` |
| `home_slot` | Increase home slots | `amount` |
| `unlock_recipe` | Unlock recipe | `value` (recipe ID) |
| `unlock_item` | Unlock item | `value` (item ID) |
| `unlock_dimension` | Unlock dimension | `value` (dimension ID) |
| `command` | Execute command | `value` (command) |

---

## 6. Dependencies

Control which quests must be completed before this one unlocks.

```json
"dependencies": {
  "required": ["quest_id_1", "quest_id_2"],  // Must complete these
  "optional": ["quest_id_3"],               // Optional dependencies
  "requireAll": true  // true = AND logic, false = OR logic
}
```

**Examples:**

- `requireAll: true` with `[A, B]` → Must complete **both** A and B
- `requireAll: false` with `[A, B]` → Must complete **either** A or B
- No dependencies → Quest available immediately

---

## 7. Unlocks System

Lock content until quest completion.

```json
"unlock": {
  "items": ["mekanism:machineblock:*"],  // Unlock all machine blocks
  "recipes": ["mekanism:generators/*"],  // Unlock generator recipes
  "dimensions": ["1"],                  // Unlock End dimension
  "jeiCategories": ["mekanism.crusher"] // Show in JEI
}
```

**Wildcard Support:**
- `modid:*` → All items from mod
- `modid:item:*` → All metadata variants
- `modid:path/*` → All items matching pattern

---

## 8. Complete Examples

### Example 1: Simple Collection Quest

```json
{
  "questId": "gather_wood",
  "chapterId": "01_getting_started",
  "title": "Gather Wood",
  "description": "Collect 64 oak logs to start your adventure.",
  "icon": "minecraft:log",
  "position": {"x": 0, "y": 0},
  
  "tasks": [
    {
      "taskId": "collect_logs",
      "type": "COLLECT",
      "item": "minecraft:log",
      "count": 64
    }
  ],
  
  "rewards": {
    "guaranteed": [
      {"type": "item", "item": "minecraft:apple", "amount": 5},
      {"type": "xp", "amount": 100}
    ]
  }
}
```

### Example 2: Tech Progression Quest

```json
{
  "questId": "tech_basic_generator",
  "chapterId": "02_basic_tech",
  "title": "Power Generation Basics",
  "description": "Craft your first Heat Generator.",
  "icon": "mekanism:basicblock:8",
  "position": {"x": 100, "y": 50},
  
  "dependencies": {
    "required": ["gather_iron"],
    "requireAll": true
  },
  
  "tasks": [
    {
      "taskId": "craft_generator",
      "type": "CRAFT",
      "item": "mekanism:basicblock:8",
      "count": 1
    }
  ],
  
  "rewards": {
    "guaranteed": [
      {"type": "item", "item": "minecraft:coal", "amount": 32},
      {"type": "aether", "amount": 500}
    ],
    "choice": {
      "choose": 1,
      "options": [
        {"type": "skill_points", "amount": 1, "description": "1 Tech Skill Point"},
        {"type": "aether", "amount": 1000, "description": "1000 Extra Æther"}
      ]
    }
  },
  
  "unlock": {
    "items": ["mekanism:machineblock:*"],
    "recipes": ["mekanism:generators/*"],
    "jeiCategories": ["mekanism.crusher"]
  },
  
  "metadata": {
    "repeatable": false,
    "hidden": false
  }
}
```

---

## 9. Best Practices

### Quest IDs
- Use descriptive names: `tech_basic_generator` not `quest1`
- Include chapter prefix: `01_getting_started_first_tree`
- Use underscores not spaces

### Task Design
- Keep counts reasonable (don't ask for 10,000 items)
- Use `consume: false` for "check" quests
- Combine multiple small tasks into one quest

### Rewards Balance
- Early quests: 100-500 Æther
- Mid-game: 500-2000 Æther
- End-game: 2000+ Æther
- Skill points: 1 per major quest

### Dependencies
- Create clear progression paths
- Avoid circular dependencies
- Test dependency chains thoroughly

### Unlocks
- Lock OP items behind progression
- Use wildcards for mod-wide unlocks
- Don't lock vanilla essentials (crafting table, furnace)

---

## 10. Troubleshooting

### Quest Not Loading
1. Check JSON syntax (use validator: jsonlint.com)
2. Verify all required fields are present
3. Check server logs for parsing errors
4. Ensure quest ID is unique

### Quest Not Appearing
1. Check `hidden: false` in metadata
2. Verify dependencies are met
3. Reload quests with `/skyzer reload quests`

### Tasks Not Tracking
1. Verify task type is correct
2. Check item/entity IDs match registry
3. Use registry dumps (this wiki!) to find correct IDs

### Unlocks Not Working
1. Verify pattern syntax (wildcards)
2. Check JEI categories exist
3. Ensure quest is marked as completed

---

## 📚 Additional Resources

- **Item Registry:** `item_registry.txt` - Find all item IDs
- **Biome Registry:** `biome_registry.txt` - Find all biome IDs
- **Entity Registry:** `entity_registry.txt` - Find all entity IDs
- **Dimension Registry:** `dimension_registry.txt` - Find all dimension IDs

**Quest Files Location:** `config/skyzer/quests/chapters/`

**Wiki Generated:** Thu Feb 12 16:18:10 CET 2026
