ArcQuest

# Arc Quest

**Arc Quest** is a data-driven quest, dialogue, and RPG content framework for Minecraft modpacks, servers, and adventure maps.

It provides a server-authoritative quest runtime, branching dialogue, NPC interactions, world markers, shops, gacha systems, in-game guides, a complete quest journal, tracking HUDs, history graphs, and visual editing tools.

> **Arc Quest is primarily a framework for content creators.**  
> The base mod does not include a complete quest campaign. Modpack authors, map makers, and server administrators create their own content through JSON files, the Web editor, or the Java API.

## Main Features

### Quest System

Create linear, branching, parallel, randomized, timed, repeatable, or collection-based quests with:

- Multiple phases and completion policies
- Conditional and player-choice transitions
- Random initial phases and phase transitions
- Automatic or manually confirmed progression
- Quest categories, groups, sorting, and tracking rules
- Phase and quest rewards
- Configurable abandonment and time limits

Built-in objectives include killing entities, collecting or delivering items, talking to NPCs, interacting with blocks or entities, reaching locations, crafting, offering items, boolean checks, and custom objective types.

### Conditions and Variables

Control quests, phases, dialogue, choices, and markers using:

- Quest and phase states
- Flags and integer variables
- Player levels and status effects
- Minecraft predicates
- Nested `AND`, `OR`, and `NOT` conditions

Persistent variables make it possible to build factions, hidden branches, story decisions, and long-running progression systems.

### Quest Journal and HUD

The player interface includes:

- Active, completed, and failed quest tabs
- Categories and groups
- Tracked quest HUD
- Objective progress and reward previews
- New quest and status notifications
- Chapter shops and phase stories
- Unread indicators
- Responsive layouts and animations

The History view displays the player’s actual route through phase topology graphs, including phase images, item icons, objectives, rewards, descriptions, and hidden unreached phases.

### Branching Dialogue

Create multi-node NPC conversations with:

- Player choices and conditional visibility
- Conditional text
- Cooldowns and entity bindings
- Dialogue actions
- Flags and variable operations
- Quest progression and marker triggers
- Dedicated dialogue UI

Quests and dialogue can reference each other through stable IDs, conditions, variables, and actions.

### NPCs, Trading, and Gacha

Arc Quest includes data-driven modules for:

- Entity-based NPC interactions
- Standalone, phase, and chapter shops
- Conditional trading availability
- Weighted gacha pools
- Rarity, weight modifiers, and pity systems

### World Markers

Quests and dialogue can create markers for positions, entities, blocks, nearby entity types, structures, phases, and objectives.

Markers may be triggered by quest acceptance, phase changes, objective completion, dialogue nodes, dialogue choices, or persistent conditions. Marker state is managed across death, relogging, dimension changes, and world switching.

### Xaero Integration

Optional integration supports:

- Xaero’s Minimap
- Xaero’s World Map
- Arc Quest diamond-style icons
- World Map hover tooltips
- Minimap icons without duplicate world beacons

Arc Quest’s native marker HUD works without Xaero.

### Guides and Ponder

Build categorized tutorials, gameplay guides, quest-unlocked entries, and Ponder scenes. Guide content can also be granted through quest phases.

## Content Creation

Arc Quest supports three authoring workflows:

### Modular Web Editor

Visually create and validate quests, phases, objectives, transitions, dialogue, NPCs, markers, trades, gacha shops, and guides. The editor supports importing, exporting, reference validation, normalization, and live Registry suggestions through WebSocket.

### In-Game Quest Editor

Administrators can inspect and edit data-backed quests through an in-game phase topology and property workspace.

### Java API

Addon developers can register custom quests, objectives, conditions, rewards, dialogue actions, marker targets, categories, and other content through public Builders, Registries, APIs, and NeoForge events.

## Safe Hot Reloading

Arc Quest validates content before applying it. Reloading includes:

- Bounded file scanning and UTF-8 JSON parsing
- Duplicate ID and cross-module reference checks
- Warning and blocking-error reporting
- Immutable candidate snapshots
- Atomic Registry replacement
- Preservation of the previous valid state after failure
- Reload epoch logging and client synchronization

Invalid files are reported with their file and field paths without clearing valid loaded content.

## Requirements

- **Minecraft:** 1.21.1
- **Mod Loader:** NeoForge
- **NeoForge:** 21.1.234 or compatible newer builds
- **Java:** 21
- **Required:** Ponder 1.0.64+
- **Optional:** Xaero’s Minimap and Xaero’s World Map

All dependencies must target Minecraft 1.21.1 and NeoForge.

## Recommended For

- RPG modpacks
- Story-driven adventure maps
- Multiplayer quest servers
- Open-world progression systems
- NPC stories and faction systems
- Tutorials and gameplay guides
- Teams needing visual content-authoring tools

## Installation

**Players:**

1. Install NeoForge and Ponder.
2. Place Arc Quest in the `mods` folder.
3. Install a compatible content pack or join a server that provides Arc Quest content.

**Content creators:**

1. Create content using the Web editor, JSON files, or Java Builders.
2. Export it to the Arc Quest data directory.
3. Run the Arc Quest reload command.
4. Correct any validation or reference errors reported.

**Arc Quest provides the framework, runtime, and interface—not a built-in campaign.** If no quests appear after installation, verify that your modpack or server includes Arc Quest content files.