NPC system

Blockfolk

Bring your world to life.

Create persistent NPCs with routes, behaviours, conversations, combat, and world interaction.

  • Paper
  • Minecraft 26.2
  • Java 25+
  • MIT

What it does

Presets and spawned instances are separate. Configure routes, equipment, interactions, and combat from inventory menus. OpenRouter is optional and only uses administrator-enabled actions.

  • Persistent NPC presets
  • In-game administration
  • Saved NPC poses
  • Behavior sequences

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

  • Saved NPC poses

    Choose standing, crouching, sleeping, sitting, swimming/crawling, or fall flying under NPC Properties → Pose; use Sitting in behavior, waypoint, and question animations

  • Behavior sequences

    React to interaction, proximity, combat, time, waypoints, custom events, and other supported triggers

  • Routes and locations

    Build NPC-owned 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

  • Abilities

    Build shared custom attacks with origins, spheres, cones, beams, teleport, timing, charged weapon hits, combined effects, and previews; assign them through Fighting & Survival or cast them with a Use Ability behaviour action

  • Shared shops

    Sell items through the vanilla trading screen with unlimited, item-for-item trades; build each shop once and open it from any NPC with the Open Shop behaviour action

  • 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

Installation

  1. 1

    Check your server

    Run Paper with Java 25 or newer, built for Minecraft 26.2. No other plugins are required.

  2. 2

    Add the JAR

    Stop the server, download Blockfolk-1.6.0.jar, and place it in plugins/. When upgrading, replace the previous JAR.

  3. 3

    Start and configure

    Start the server and check the console. Review the generated configuration with the release documentation.

First command
/bf create

Create a reusable NPC preset in the dialog, configure it in the editor, and spawn a persistent instance.

Commands13

CommandDescription
/bf or /blockfolkOpen the NPC preset browser
/bf createOpen the NPC creation dialog for name, HP, respawn time, and basic properties
/bf create <name>Open the creation dialog with the name prefilled
/bf npc <name>Open a preset editor; names are tab-completed
/bf npc <name> editOpen the same preset editor explicitly
/bf npc <name> spawnSpawn a persistent instance of a preset
/bf npc <name> duplicateDuplicate a preset with (copy) appended to its name
/bf abilitiesOpen the shared attack library and editor
/bf shopOpen the shared shop library
/bf shop create <name>Create a shared shop
/bf shop <shop> [rename|preview]Rename a shop or preview its trades
/bf routesOpen the route manager
/bf locationsOpen the global-location manager

Permissions1

PermissionDescriptionDefault
blockfolk.adminCreate, edit, spawn, and manage Blockfolk NPCsop

Configuration6

SettingPurpose
chat-input-timeout-secondsTime allowed for administrator text input
question-timeout-secondsTime allowed for a player to answer an NPC question
proximity-transition-cooldown-secondsDebounces rapid approach and leave transitions
mineskin-api-keyOptional 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

Release notes

Blockfolk v1.6.0

Blockfolk 1.6.0 adds shared shops in the vanilla trading screen and an Open Shop behaviour action, building on the custom ability shapes, triggers, and effects added in 1.5.0.

Questions or an issue?

Bug reports, questions, and contributions go to this plugin’s GitHub repository.

Open an issue