RUNESTONE VALE

RunestoneNPCs

The NPC, dialogue, quest, and shop runtime of RunestoneMMO — built to make NPCs feel like real parts of the realm.

RunestoneNPCs is the authoritative NPC gameplay module for the RunestoneMMO ecosystem. It owns NPC bindings, dialogue packages, quest packages, quest state resolution, quest offers, quest rewards, NPC shop packages, NPC shop bindings, and click-open runtime behavior for Runestone Vale.

RunestoneNPCs works alongside Citizens, but does not replace it. Citizens owns the physical NPC entity. RunestoneNPCs owns the MMO gameplay attached to that NPC: what dialogue appears, what quests are offered, what shops open, how quest state progresses, and how NPC interaction behaves.

In simple terms: Citizens creates the NPC body, RunestoneCore exposes the bridge commands, AdminTool gives staff a cleaner GUI, and RunestoneNPCs owns the NPC gameplay.

RunestoneMMO on Hangar Join the Discord Back to Runestone Vale

Platform: Minecraft Java Edition • Paper 1.21.11 • Java 21
Requires: RunestoneCore
Integrates With: Citizens • RunestoneAdminTool • RunestoneHub

What RunestoneNPCs Owns

RunestoneNPCs owns the NPC MMO runtime. It is the source of truth for NPC content behavior, while Core and AdminTool provide command bridges and staff-facing workflow access.

NPC Bindings

Connects Citizens NPC IDs to Runestone binding data, dialogue packages, quest offers, daily pools, and shop packages.

Dialogue Runtime

Displays multi-state and multi-page dialogue based on player quest state, NPC configuration, and package data.

Quest Runtime

Owns quest packages, lifecycle state, objective tracking, rewards, completion handling, and quest service integration.

NPC Shops

Owns curated NPC shop packages, NPC shop bindings, shop editor behavior, and buy/sell interaction runtime.

Newest NPC Highlights

Recent RunestoneNPCs work has focused on moving NPCs toward a true MMO-style content pipeline: stronger quests, modern offers, better dialogue state handling, in-game authoring, NPC shops, Hub Quest Info support, and safer lifecycle behavior.

Runtime Authority Split

NPC bindings, dialogue, quests, quest offers, daily pools, and shops now belong to RunestoneNPCs instead of being treated as Core-owned config content.

Quest Service Provider

RunestoneNPCs registers the active quest service implementation used by Core scoreboards, Hub Quest Info, and read-only quest displays.

Modern Multi-Offer NPCs

NPCs can use modern offer bindings with offer IDs, order, enabled state, repeatable/daily flags, prerequisites, level requirements, and visibility rules.

Quest Completion UX

Objective-complete notifications and quest-completion dialogue screens are supported, including reward summary feedback for the player.

NPC Shop Runtime

NPC shops support curated buy/sell behavior through authoritative shop packages and exact ItemStack-backed listings added from held items.

In-Game Authoring Direction

Normal staff workflow is through /rnpc and AdminTool, while YAML files act as persistence backends rather than the preferred manual editing path.

Module Boundary

RunestoneNPCs is powerful because its ownership is clear. It owns the NPC MMO runtime, but it does not own Citizens entities, Core command registration, AdminTool menus, Hub rendering, or unrelated economy/player-shop systems.

RunestoneNPCs Owns

  • NPC binding runtime
  • NPC dialogue package runtime
  • NPC quest package runtime
  • Quest lifecycle and player quest state resolution
  • Quest reward resolution and completion handling
  • Modern multi-offer quest bindings
  • Per-NPC daily pool runtime support
  • NPC shop package runtime
  • NPC shop editor and open behavior
  • npcs.yml, quests.yml, and shops.yml persistence authority

Other Systems Own

  • Citizens owns NPC entities, selection, spawning, despawning, movement, and physical NPC existence.
  • RunestoneCore owns the temporary /rnpc command/bridge surface, quest service interface, scoreboards, economy APIs, and shared services.
  • RunestoneAdminTool owns staff GUI workflows and selected-NPC orchestration.
  • RunestoneHub owns the player Hub UI and read-only Quest Info display.
  • RunestoneSkills owns skill XP and skill definitions used by quest rewards/requirements.
  • RunestoneCombat owns combat XP/runtime behavior used by combat quest rewards.

Main Systems Inside RunestoneNPCs

NPC Bindings

  • Binding data lives under npc.bindings.<npcId>.*
  • Supports base binding keys
  • Supports dialogue binding
  • Supports modern multi-offer quest bindings
  • Supports shop binding
  • Supports daily pool data paths
  • Binding data persists in npcs.yml

Dialogue Packages

  • Dialogue data lives under npc.dialogues.<dialogueKey>
  • Supports package title
  • Supports dialogue panel title
  • Supports NPC display name
  • Supports labels, buttons, layout, objective, rewards, and icon metadata
  • Supports state-specific lines and pages
  • Dialogue packages persist in npcs.yml

Dialogue States

  • offer — before the player accepts the quest
  • active — while the quest is active
  • ready_to_turn_in — when objectives are complete and the player can turn in
  • completed — after the quest is completed
  • Supports states.<state>.lines
  • Supports states.<state>.pages.<n>.lines
  • Supports fallback pages.<n>.lines and lines

Quest Packages

  • Quest data lives under npc.quests.<questKey>
  • Supports title, summary, objective, type, target, and amount
  • Supports location and radius for discovery quests
  • Supports reward preview lines
  • Supports currency, skill XP, combat XP, and item rewards
  • Quest packages persist in quests.yml

Supported Quest Types

  • INVENTORY_ITEM — checks for items in inventory
  • DELIVER_ITEM — checks and consumes required items on turn-in
  • KILL_MOB — tracks valid entity kills
  • INTERACT_NPC — tracks NPC interaction objectives
  • DISCOVER_LOCATION — tracks arrival at configured location/radius
  • Trainer, travel, reputation, and complex branching quest types are not live

Quest Lifecycle

  • AVAILABLE
  • ACTIVE
  • READY_TO_TURN_IN
  • COMPLETED
  • Also supports failed, abandoned, and repeat-cooldown style states where relevant
  • Legacy state aliases are normalized into canonical lifecycle values
  • Player state uses keys such as quest.<questKey>.state and quest.<questKey>.progress

Quest Rewards

  • Currency rewards
  • Skill XP rewards
  • Combat XP rewards
  • Item rewards
  • Reward preview support
  • Completion GUI reward summary support
  • Reward granting is designed to avoid duplicate reward exploits

Quest Offers

  • Modern offer path: npc.bindings.<npcId>.quests.<offerId>.*
  • Offer points to a quest package
  • Supports offer ordering
  • Supports enabled/disabled state
  • Supports repeatable and daily flags
  • Supports completed-quest prerequisites
  • Supports level requirements
  • Supports visibility behavior for unmet requirements

Daily Quest Pools

  • Per-NPC daily pool data path exists under npc.bindings.<npcId>.daily_pool.*
  • Supports per-player rolled daily offers in runtime direction
  • Designed for future daily/repeatable NPC quest content
  • Daily pool editing UI is not first-version live scope
  • Static offer workflows remain separate from daily pool workflows

NPC Shops

  • Shop definitions live under npc.shops.<shopKey>
  • NPC shop binding path: npc.bindings.<npcId>.shop
  • Supports in-game shop editor
  • Supports shop preview
  • Supports exact held ItemStack listings
  • Supports custom Oraxen items where the item exists in the held stack
  • Shop data persists in shops.yml

NPC Shop Modes

  • BUY_ONLY — players buy from the NPC
  • SELL_ONLY — players sell to the NPC
  • BUY_AND_SELL — NPC supports both buy and sell behavior
  • Valid menu sizes: 9, 18, 27, 36, 45, 54
  • Shop editor remains the safest way to manage listings

Runtime Reload

  • /rnpc reload refreshes NPC runtime authority
  • Refreshes config-backed NPC data
  • Re-registers NPC-owned listeners where needed
  • Does not wipe player quest progress
  • Does not wipe bindings, dialogues, quests, or shops data

NPC Interaction Flow

NPC interaction follows a clear ownership model. Citizens provides the clickable NPC entity, RunestoneNPCs resolves what the NPC should do, and Core/AdminTool provide bridge surfaces for staff.

When a Player Clicks an NPC

  • Citizens handles the physical NPC entity
  • RunestoneNPCs checks the NPC binding
  • If a valid shop is bound, the NPC shop can open
  • If dialogue/quest data is bound, the interaction opens the correct dialogue/quest state
  • Quest state determines whether the player sees offer, active, ready, or completed dialogue

Player Quest Data

  • Tracks active quest state
  • Tracks objective progress
  • Tracks completed quests
  • Tracks ready notification flags for anti-spam behavior
  • Tracks daily availability where daily offers are used
  • Exposes read-only snapshots through the quest service boundary

Hub & Scoreboard Integration

  • RunestoneNPCs provides quest data through RunestoneQuestService
  • RunestoneHub reads quest info through the service
  • Core scoreboards read quest placeholders through the service
  • Core does not directly mutate RunestoneNPCs quest state through display systems

Commands & Permissions

RunestoneNPCs itself does not need a large public player command root. The live operational command surface is exposed through the Core-side /rnpc bridge and AdminTool workflows.

Main Bridge Command

  • /rnpc — main NPC admin bridge command
  • /runpc — alias
  • /rnpcs — alias
  • /rnb — convenience alias for bind workflows
  • /rnd — convenience alias for dialogue workflows
  • /rnq — convenience alias for quest workflows
  • /rndb — convenience alias for debug workflows
  • /rnm — convenience alias for metadata workflows
  • /rno — convenience alias for open workflows

Permission

  • runestonecore.npc.admin
  • Default: OP
  • Required for the /rnpc admin bridge surface
  • Used by staff/admin NPC management workflows

Base NPC Commands

  • /rnpc select nearest
  • /rnpc bind create <npcId>
  • /rnpc bind <npcId> <bindingKey>
  • /rnpc unbind <npcId>
  • /rnpc debug <npcId> [player]
  • /rnpc meta <npcId>
  • /rnpc meta <npcId> sync
  • /rnpc open <npcId> [player]
  • /rnpc reload

Dialogue Commands

  • /rnpc dialogue <npcId> <dialogueKey>
  • /rnpc dialogue unbind <npcId>
  • /rnpc dialogue create <dialogueKey>
  • /rnpc dialogue delete <dialogueKey>
  • /rnpc dialogue property <dialogueKey> <path> <value>
  • /rnpc dialogue info <dialogueKey>
  • /rnpc dialogue validate <dialogueKey>
  • /rnpc bind dialogue <npcId> <dialogueKey>

Quest Package Commands

  • /rnpc quest create <questKey>
  • /rnpc quest delete <questKey>
  • /rnpc quest title <questKey> <title>
  • /rnpc quest summary <questKey> <summary>
  • /rnpc quest objective <questKey> <objective>
  • /rnpc quest type <questKey> <type>
  • /rnpc quest target <questKey> <target>
  • /rnpc quest amount <questKey> <amount>
  • /rnpc quest repeatable <questKey> <true|false>
  • /rnpc quest daily <questKey> <true|false>
  • /rnpc quest enable <questKey>
  • /rnpc quest disable <questKey>
  • /rnpc quest location <questKey>
  • /rnpc quest radius <questKey> <radius>
  • /rnpc quest property <questKey> <path> <value>
  • /rnpc quest info <questKey>
  • /rnpc quest validate <questKey>

Quest Reward Commands

  • /rnpc quest reward list <questKey>
  • /rnpc quest reward add currency <questKey> <currencyId> <amount>
  • /rnpc quest reward remove currency <questKey> <currencyId>
  • /rnpc quest reward add skillxp <questKey> <skillId> <amount>
  • /rnpc quest reward remove skillxp <questKey> <skillId>
  • /rnpc quest reward add item <questKey> <itemId> <amount> [material]
  • /rnpc quest reward remove item <questKey> <index>
  • /rnpc quest reward set combatxp <questKey> <amount>
  • /rnpc quest reward clear combatxp <questKey>

Quest Offer Commands

  • /rnpc offer list <npcId>
  • /rnpc offer set <npcId> <offerId> <questKey>
  • /rnpc offer remove <npcId> <offerId>
  • /rnpc offer repeatable <npcId> <offerId> <true|false>
  • /rnpc offer daily <npcId> <offerId> <true|false>
  • /rnpc offer order <npcId> <offerId> [order]
  • /rnpc offer enable <npcId> <offerId>
  • /rnpc offer disable <npcId> <offerId>
  • /rnpc offer visibility <npcId> <offerId> <hidden|locked>
  • /rnpc offer require add|remove|list <npcId> <offerId> [questKey]
  • /rnpc offer level set|remove|list <npcId> <offerId> [skillId] [level]

NPC Shop Commands

  • /rnpc shop create <shopKey>
  • /rnpc shop edit <shopKey>
  • /rnpc shop title <shopKey> <title>
  • /rnpc shop mode <shopKey> <BUY_ONLY|SELL_ONLY|BUY_AND_SELL>
  • /rnpc shop buytitle <shopKey> <title>
  • /rnpc shop selltitle <shopKey> <title>
  • /rnpc shop buysize <shopKey> <9|18|27|36|45|54>
  • /rnpc shop sellsize <shopKey> <9|18|27|36|45|54>
  • /rnpc shop addhand <shopKey> <price> [currencyId]
  • /rnpc shop remove <shopKey> <index>
  • /rnpc shop list <shopKey>
  • /rnpc shop bind <npcId> <shopKey>
  • /rnpc shop unbind <npcId>
  • /rnpc shop open <npcId> [player]
  • /rnpc shop preview <shopKey>

Configuration & Runtime Files

RunestoneNPCs uses split configuration files. These files are authoritative persistence backends, but normal staff authoring should happen through /rnpc commands and AdminTool workflows.

npcs.yml

  • NPC bindings
  • Binding defaults
  • Dialogue package data
  • NPC GUI defaults
  • Dialogue labels, buttons, layouts, and display tuning
  • Per-NPC quest offer bindings
  • Per-NPC shop binding keys

quests.yml

  • Quest package data
  • Quest title, summary, objective, type, target, and amount
  • Discovery quest location/radius data
  • Reward preview data
  • Currency, skill XP, combat XP, and item rewards
  • Daily pool-related quest data where configured

shops.yml

  • NPC shop package data
  • Shop title
  • Shop mode
  • Buy and sell page titles
  • Buy and sell page sizes
  • Buy and sell listings
  • Exact ItemStack-backed shop entries

Runtime Rule

  • YAML is persistence, not the preferred manual workflow
  • Use /rnpc for command authoring
  • Use AdminTool for staff-facing GUI workflows
  • Use /rnpc reload after config/runtime changes when needed
  • Do not edit player quest state by hand unless specifically instructed

AdminTool Integration

AdminTool gives staff a safer interface for NPC work, but it does not become a second NPC backend. It routes NPC actions through Citizens and the live /rnpc bridge.

Citizens-Side Actions

  • Create NPC
  • Select nearest NPC
  • Teleport to selected NPC
  • Highlight selected NPC
  • Reuse selected NPC context across follow-up actions

RunestoneNPC Actions

  • Bind and unbind NPCs
  • Debug NPCs
  • View and sync NPC metadata
  • Open NPC GUI
  • Bind or unbind dialogue
  • Bind quest offers
  • Bind and unbind shops
  • Reload NPC runtime

Authoring Workflows

  • Browse existing dialogue packages
  • Create/edit/delete dialogue packages
  • Browse existing quest packages
  • Create/edit/delete quest packages
  • Manage quest rewards
  • Manage quest offers
  • Create/edit/preview NPC shops
  • Add and remove shop listings

Recommended Staff Workflow

Creating a Quest NPC

  • Create or select the Citizens NPC
  • Run /rnpc select nearest
  • Run /rnpc bind create <npcId>
  • Create a dialogue package
  • Create a quest package
  • Set quest type, target, amount, and rewards
  • Bind the quest to the NPC as an offer
  • Bind dialogue to the NPC
  • Validate dialogue and quest packages
  • Run /rnpc reload
  • Test as a normal player

Creating an NPC Shop

  • Create or select the Citizens NPC
  • Run /rnpc bind create <npcId>
  • Run /rnpc shop create <shopKey>
  • Set title, mode, and page sizes
  • Hold item and use /rnpc shop addhand
  • Use /rnpc shop edit <shopKey> for safer listing management
  • Preview the shop
  • Bind the shop to the NPC
  • Run /rnpc reload
  • Test as a normal player

Validation Commands

  • /rnpc debug <npcId>
  • /rnpc offer list <npcId>
  • /rnpc dialogue validate <dialogueKey>
  • /rnpc dialogue info <dialogueKey>
  • /rnpc quest validate <questKey>
  • /rnpc quest info <questKey>
  • /rnpc quest reward list <questKey>
  • /rnpc shop list <shopKey>
  • /rnpc shop preview <shopKey>

Important Staff Notes

RunestoneNPCs is built to support a professional content pipeline. That means staff should use the live tools, validate content, and avoid bypassing the runtime with unsafe manual edits.

Do

  • Use AdminTool when possible
  • Use /rnpc commands for NPC gameplay logic
  • Use exact Bukkit material/entity names
  • Validate quest and dialogue packages
  • Use /rnpc debug before assuming a bug
  • Test as a normal non-op player

Do Not

  • Do not assume Citizens owns quest/shop behavior
  • Do not manually edit YAML as the default workflow
  • Do not use obsolete single-field quest binding as the main workflow
  • Do not fake quest rewards through unrelated commands
  • Do not create duplicate unclear quest keys
  • Do not reload Citizens unless the Citizens NPC entity itself requires it

Compatibility & Structure

Platform

  • Server: Paper
  • Minecraft: 1.21.11
  • Java: 21
  • Architecture: Gradle multi-module

Dependencies

  • Required: RunestoneCore
  • Required for NPC entities: Citizens
  • Integrates With: RunestoneAdminTool
  • Read By: RunestoneHub Quest Info and Core scoreboards through quest service snapshots

Lifecycle

  • Loads NPC config authority
  • Loads dialogue packages
  • Loads quest packages
  • Loads shop packages
  • Registers quest service provider
  • Registers NPC interaction/listener behavior
  • Supports runtime reload without wiping player progress

What Is Still Growing Inside RunestoneNPCs

RunestoneNPCs already provides the current NPC, dialogue, quest, offer, and shop runtime foundation. The system is strong enough for real content, but the long-term MMO vision still leaves room for more depth.

More Quest Content

The engine supports live quest authoring, but Runestone Vale still needs more actual questlines, tutorials, daily quests, and region-based story content.

Daily Pool Editing

Daily pool runtime paths exist, but full AdminTool pool editing UI is deferred beyond the first-version scope.

Advanced Dialogue Tooling

Multi-state and multi-page dialogue is live, while deeper narrative tooling and complex page management can grow later.

More NPC Shop Content

NPC shops are ready for curated vendors, but the realm still needs more polished shop packages, themed vendors, and economy-connected listings.

Future Quest Types

Trainer, travel, reputation, branching, and advanced quest types are intentionally not live yet and should be added only after the current system is stable.

World Content Integration

NPC quests can grow into dungeons, boss arenas, discoveries, towns, events, and long-term world storytelling as content expands.

State of the Module

RunestoneNPCs is actively serving as the NPC gameplay runtime for Runestone Vale. It provides the authority behind NPC bindings, dialogue states, quest packages, quest offers, rewards, shops, and quest service data.

Current development is focused on making NPC content easier to author, safer to validate, and more connected to Hub displays, scoreboard information, AdminTool workflows, and future server content.

This is the NPC content engine of RunestoneMMO — the layer that turns static NPCs into quest givers, shopkeepers, guides, storytellers, and living parts of the realm.

Build the World Through NPCs

RunestoneNPCs gives staff the tools to turn Citizens NPCs into meaningful Runestone Vale content: quests, dialogue, shops, rewards, turn-ins, tutorials, and future storylines.

RunestoneMMO on Hangar See RunestoneCore See RunestoneAdminTool View Server Features Join the Discord