Cobbleworks - Blockfolk NPC Plugin

Create persistent fake-player NPCs without editing data files by hand.
Build personalities, routines, routes, conversations, combat profiles, and optional AI behavior through in-game menus.

          

Blockfolk is a GUI-driven NPC system for Paper servers. Administrators create reusable NPC presets, spawn persistent instances, and configure their appearance and behavior from inventory menus. NPCs can follow routes, react to players and world events, fight, gather resources, move items, hold conversations, and integrate with quests. Optional OpenRouter support lets an NPC choose only from the actions that an administrator explicitly enables.

Core Features

• Persistent NPC presets: Reuse one definition across multiple independently stored instances
• In-game administration: Configure skins, equipment, names, dialog, inventories, routes, and behavior without hand-editing YAML
• Behavior sequences: React to interaction, proximity, combat, time, waypoints, custom events, and other supported triggers
• Routes and locations: Build walking routes in the world and reuse named destinations across NPCs
• Configurable combat: Define attacks, targets, alliances, loot, experience, respawn timing, and nearby boss bars
• World interaction: Mine configured resources, harvest crops, and transfer items to or from containers
• Optional AI behavior: Use OpenRouter for contextual conversation and validated, administrator-approved actions
• Quest integration: Expose persistent Blockfolk NPCs directly to BeautyQuests

Supported Platforms

• Server Software: Paper
• Minecraft Version: 26.2
• Java Requirement: Java 25+
• Optional Integrations: BeautyQuests, OpenRouter

Table of Contents

1. Core Features
2. Supported Platforms
3. Getting Started
   • Prerequisites
   • Installation Steps
   • Verifying Installation
4. Third-Party Plugins and Services
   • BeautyQuests
   • OpenRouter
5. Configuration
6. How It Works
   • Presets and Instances
   • Behaviors and Routes
   • AI Behavior
7. Commands
8. Permissions
9. Documentation
10. Building from Source
11. License
12. Screenshots

Getting Started

Prerequisites

• A Paper 26.2 server
• Java 25 or newer
• Operator access or the blockfolk.admin permission

BeautyQuests and OpenRouter are optional. Blockfolk's deterministic NPC system works without either integration.

Installation Steps

1. Download the latest Blockfolk-x.x.x.jar from Releases
2. Stop the server and copy the jar into its plugins/ directory
3. Start the server once to create plugins/Blockfolk/config.yml and the plugin data files
4. Run /bf to open the NPC preset browser
5. Create a preset, configure it, and use its Spawn action to place a persistent instance

Verifying Installation

• Run /plugins and confirm that Blockfolk is shown in green
• Run /bf and confirm that the preset browser opens
• Create a test NPC and restart the server to confirm that its instance returns

Third-Party Plugins and Services

BeautyQuests

BeautyQuests is an optional soft dependency. When installed, spawned Blockfolk NPCs appear in BeautyQuests' NPC selector. Quest starters, stages, markers, and navigation pauses refer to the NPC's persistent instance UUID, so assignments survive restarts and combat respawns.

OpenRouter

OpenRouter is optional and is contacted only for presets with AI behavior enabled. Configure openrouter.api-key and openrouter.model in config.yml. Requests run asynchronously, and returned actions are checked against the capabilities enabled for the preset; model output cannot execute arbitrary commands or code.

API usage may incur charges under the selected provider's terms. Keep the API key private and never commit a populated server configuration.

Configuration

The default config.yml controls input timeouts, proximity transition cooldowns, MineSkin access, OpenRouter requests, AI throttling, conversation history, perception limits, mining limits, and temporary-inventory capacity.

Setting	Purpose
chat-input-timeout-seconds	Time allowed for administrator text input
question-timeout-seconds	Time allowed for a player to answer an NPC question
proximity-transition-cooldown-seconds	Debounces rapid approach and leave transitions
mineskin-api-key	Optional key for higher MineSkin request limits
openrouter.*	Endpoint, key, model, timeout, and response limit for optional AI behavior
ai-control.*	AI cooldown, memory, perception, mining, and inventory safeguards

See the configuration reference for every option and its default value.

How It Works

Presets and Instances

A preset stores shared appearance and behavior. Each spawned instance has its own persistent UUID, position, inventory, conversation state, and respawn deadline. Editing a preset updates its spawned copies while preserving the identities used by integrations.

The Manage Instances menu provides shortcuts for teleporting to an NPC, moving it and its respawn point, or removing it with confirmation. Shift-right-clicking a spawned NPC opens its preset editor directly.

Behaviors and Routes

Behavior sequences contain ordered actions attached to an event. NPCs can speak, wait, walk, fight, mine, harvest, work with containers, ask questions, invoke custom events, or hand control to the optional AI layer. Routes combine world waypoints with their own arrival actions.

Mining, harvesting, and container transfers emit cancellable Bukkit events so claim, region, and logging plugins can approve, reject, or record the world change.

AI Behavior

AI context is configured per preset through Identity, Personality & Behavior, Goal / Role, and Knowledge / Information. An AI Trigger behavior action invokes the model for the surrounding event. Nearby chat can also be enabled independently.

Conversation memory can be private per player or shared by everyone speaking to an instance. Optional long-term memory stores up to 45 validated facts per preset. While a request is active, a small thinking indicator appears above participating NPCs; queued interactions resume after the request or cooldown completes.

Commands

Command	Description
/bf or /blockfolk	Open the NPC preset browser
/bf create	Start preset creation and enter the name in chat
/bf create <name>	Create a preset with the supplied name
/bf npc <name>	Open a preset editor; names are tab-completed
/bf npc <name> spawn	Spawn a persistent instance of a preset
/bf npc <name> duplicate	Duplicate a preset with (copy) appended to its name
/bf routes	Open the route manager

Permissions

Permission	Description	Default
blockfolk.admin	Create, edit, spawn, and manage Blockfolk NPCs	op

Documentation

The full administrator guide is available at cobbleworks.github.io/Blockfolk-NPC-Plugin. Its source is kept in docs/.

To preview it locally:

cd docs
npm ci
npm run docs:dev

Building from Source

Requirements: Java 25 and Maven 3.9+

git clone https://github.com/Cobbleworks/Blockfolk-NPC-Plugin.git
cd Blockfolk-NPC-Plugin
mvn clean verify

The plugin jar is written to target/Blockfolk.jar.

License

This project is licensed under the MIT License. See LICENSE for details.

Screenshots

Blockfolk - NPC Editor	Blockfolk - Idle Walking Action
Blockfolk - AI Item Pickup	Blockfolk - Default Inventory
Blockfolk - Container Withdrawal	Blockfolk - AI Personality Response