Scuffed NPCs

Install, authoring, staff-command, permission and integration reference for server operators. For how the NPCs, quests, bounty boards and guild workers play, see the Scuffed NPCs gameplay guide.

• Plugin version: 1.98.34 (plugin name ScuffedNPCs)

All commands live under one root: /snpc (alias /scuffednpcs). Data lives in mods/Zbeve_ScuffedNPCs/.

Requirements

Engine version: >=0.7.0-pre.0 <0.8.0. The mod ships its own asset pack (NPC roles, models, UI pages, items, sounds). Nothing else is required to boot: every optional integration is looked up at runtime and switched off with a log line when missing.

Other soft integrations that are detected by class name and used only when present: ScuffedProtection, WorldProtect, OrbisGuard, SimpleClaims (workers never build or open containers where the owner could not), BetterLootBox (event keys), Endless Fates, Endless Rifts, EndlessLink (tutorial steps), and ZenShop (a tutorial purchase step).

The shipped bounty pools pay coin with the console command eco give {total} {player}. Install an economy plugin that provides that command, or edit the pools.

Quick start

1. Start the server once. The data folder and the default files are created.
2. Run /snpc quests to open the NPC hub, click + Spawn, pick a model, and place the NPC where you stand.
3. Attach a profile or a quest role (see NPC hub) so the NPC has something to say.
4. Put down the bounty boards you want with /snpc bounty place --board <id>.
5. Give guild leaders the worker items (Sacrificial Altar and Mining Site blocks) and check the hire prices with /snpc cost list.

NPC hub (/snpc quests)

/snpc quests (also /snpc npcs) opens the admin hub. It has three tabs along the top: Quests, Questlines and Quest Wizard. The left list shows placed NPCs, the right panel edits the selected one:

Placed NPCs are saved to companions.json and come back after restarts. A tool that adds records to companions.json can be picked up without a restart with /snpc reload.

Two ways to make a quest giver

Auto-bind (about 30 seconds). Write the quest and its dialogue in Endless Leveling: a dialogue block with giver_npc, turnin_npc and offer, active, turnin, done lines. Endless Leveling exports campaign_dialogues.json when it loads quests. In the hub, spawn an NPC and pick the role in Quest NPC role. The NPC then shows the right stage per player, with markers, and credits npc_talk objectives. One role handles every quest it gives or turns in. Scuffed NPCs finds the export by scanning mods/*/campaign_dialogues.json.

Custom profile (full control). Use New Profile for a ready-made offer, active, turn-in and done skeleton, then edit it in the profile editor (Stages, Dialogue, Quest Rules and Hooks tabs). Saving writes profiles/<id>.json and applies at once. Attach it to the NPC from the Profile dropdown.

The Quest Wizard builds a quest giver in four steps: pick a quest, pick a model, write one line per quest state, and choose a position. The Quests tab (also /snpc questeditor, alias /snpc editquests) browses and edits every quest on the server (rewards, trigger, prerequisite, objective, dialogue).

Profile files

Profiles live in mods/Zbeve_ScuffedNPCs/profiles/*.json. Hand-written files are picked up on boot and by /snpc reload. A reload only adds or replaces profiles; deleting a file does not remove the profile from memory (use the editor's delete for that).

{
  "id": "elder",
  "name": "Village Elder",
  "scope": "SHARED",
  "npcKey": "elder",
  "startStage": "offer",
  "stages": {
    "offer":  { "mode": "idle", "dialogue": "offer",  "marker": "available" },
    "active": { "mode": "idle", "dialogue": "active", "marker": "progress" },
    "turnin": { "mode": "idle", "dialogue": "turnin", "marker": "turnin" },
    "done":   { "mode": "idle", "dialogue": "done" }
  },
  "dialogues": {
    "offer":  { "text": "Boars are trampling our fields. Cull five of them.", "choices": [] },
    "active": { "text": "The hunt is not finished.", "choices": [] },
    "turnin": { "text": "You did it. Claim your reward in your quest log.", "choices": [] },
    "done":   { "text": "Thank you again.", "choices": [] }
  },
  "rules": [
    { "when": [ { "type": "QUEST_STATE", "quest": "elder_boar_cull", "states": ["TURN_IN_READY"] } ], "stage": "turnin" },
    { "when": [ { "type": "QUEST_STATE", "quest": "elder_boar_cull", "states": ["COMPLETED"] } ],     "stage": "done" },
    { "when": [ { "type": "QUEST_STATE", "quest": "elder_boar_cull", "states": ["IN_PROGRESS"] } ],   "stage": "active" },
    { "when": [], "stage": "offer" }
  ],
  "transitions": []
}

Rules are checked top to bottom and the first match wins, so put the most specific first. Quest states are NOT_STARTED, IN_PROGRESS, TURN_IN_READY (Endless Leveling status completed but not claimed) and COMPLETED (claimed).

Conditions (type): QUEST_STATE (quest, states), QUEST_PROGRESS_ATLEAST (quest, amount), FLAG (key, optional value).

Transition triggers (on): ON_SPAWN, DIALOGUE_CHOICE (value = choice id), VOLUME_TAG (trigger volume id), QUEST_STARTED, QUEST_COMPLETED, QUEST_CLAIMED (value = quest id), ON_HIT, ON_DEATH, ON_REACH, ON_WORLD_CHANGE (value = world name).

Actions (type, value, value2, optional cooldownMs):

RUN_COMMAND is also how a dialogue answer opens another mod's shop or menu.

Appearance and naming data

npc_names.json, npc_skins.json, portraits.json, paths.json, campaign_points.json and the bounty files are seeded from the jar when missing and never overwritten. The seeded npc_names.json has entries for the Endless Leveling starter campaign roles (Tutorial_Guide, Guild_Registrar, Auctioneer, Trial_Master, Guild_Master) and the five bounty boards, and npc_skins.json has class outfits (Class_Adventurer, Class_Arcanist, ...), so edit or delete them to suit your server. /snpc reload re-reads names and skins and re-dresses live NPCs.

Questline designer (/snpc questlines)

Authors a multi-step questline end to end and publishes it live through Endless Leveling's quest engine. It needs an Endless Leveling build with the quest-authoring provider. Each step has a name, an objective, a match key, a target count, rewards (XP, essence, cores, console commands, reward text), a giver NPC and four dialogue sets (offer, active, turn-in, done). The designer scaffolds a profile for each giver. Lines are saved in questlines.json (with a .bak copy).

Objective types: talk to an NPC, kill mobs, harvest blocks, visit a zone, clear a wave gate, clear a raid, gain levels, prestige, collect items, craft items, bring items to an NPC (optionally consumed), pick race, pick class, confirm identity, try a temporary build, spend skill points, use a dungeon portal, use a raid portal, and a scripted step. Steps that need a match key (kill, talk, and so on) refuse to publish with it blank, because an empty key would match anything.

Bounty boards

A board is an NPC that posts a short list of contracts every day. Everything is data-driven.

Placing boards

The board id can be left off when only one board is loaded. A simulate pin never expires by itself and survives restarts, so release it on a live server. /snpc reload also re-reads the bounty pools.

Files

A board is one file: bounties_<id>.json is the <id> board, and bounties.json with no suffix is the farmer board. The optional bounty_<id>.template.json holds what its NPC says; a board without one uses bounty_generic.template.json. Five boards ship: farmer, butcher, miner, hunter and professions. The professions files are only written while ScuffedProfessions is installed. Deleting a pool file stops that board on the next reload, except that missing shipped files are restored on boot.

The day's roll depends only on the date, so a restart gives the same contracts. The date follows Endless Leveling's daily reset clock and falls back to the UTC date, with one warning, when that clock is unavailable. Editing a pool re-rolls the current day.

Pool top level:

Two boards may not share an npcKey, profileId or questIdPrefix. The second one is refused and both are named in the log. The legacy farmer pool also reads farmerNpcKey and farmerProfileId.

One entry from the shipped farmer pool:

{
  "id": "wheat_granary",
  "group": "staple",
  "match": "Plant_Crop_Wheat_Item",
  "displayName": "Wheat",
  "amount": { "min": 16, "max": 32, "step": 8 },
  "chunk": 8,
  "value": 12,
  "weight": 1.0,
  "questName": "Wheat for the Granary",
  "description": "The granary is running low. Bring the farmer {amount} Wheat.",
  "rewardItems": [ { "item": "Plant_Seeds_Wheat_Eternal", "amount": 2 } ],
  "dialogue": {
    "offer":  ["Granary's near empty. {amount} Wheat, {total} coin."],
    "active": ["Still short on Wheat."],
    "turnin": ["That's the lot. Come see me for your pay."],
    "done":   ["Granary's full. Board resets at first light."]
  }
}

A day never posts the same match twice on one board and prefers not to post two from the same group. Problems are reported in the log and by /snpc bounty list. An entry that pays nothing, has a duplicate id, or puts a wildcard in a hand-in match is rejected on its own while the rest of the pool still loads. A chunk that does not divide every possible amount is dropped (the entry stays), chunk and keep on a kill or mining contract are ignored, and item ids the server does not know are named in the log once per boot.

Payouts. rewardCommands run on the console when the contract is claimed. {player} and {player_uuid} are filled by Endless Leveling. rewardItems are handed over by the NPC with amount (flat) or perUnit (scales with the ask). A count of at least 1 always comes out, and extras that do not fit land at the player's feet.

Tokens usable in names, descriptions, dialogue and reward commands: {amount}, {chunk}, {display}, {item}, {value}, {total} (value times amount), {xp}, {group}, {items}, {items+}.

Voice templates. bounty_<id>.template.json holds the words and labels. Anything repeated per contract uses {{slot. tokens and is cloned once per posted contract. Gates __ifChunk, __ifTrigger and __ifNotTrigger choose which contracts an element is cloned for. The generated profile is rewritten every day, so never edit it.

Quest host (Endless Leveling directors)

Scuffed NPCs can run three of Endless Leveling's quest directors itself, so their NPCs use the Scuffed NPCs dialogue page:

Endless Leveling keeps the quest catalog (quests.json and its config.events, config.daily_givers, config.bounties sections) and player quest progress. At boot Scuffed NPCs claims a capability only when the Endless Leveling build exposes every method the host needs, then Endless Leveling stands its own director down. Older builds without the provider API keep running all three themselves, and /snpc questhost status reports that nothing is hosted and why. When Scuffed NPCs stops, its NPCs despawn and Endless Leveling's directors resume.

mods/Zbeve_ScuffedNPCs/questhost.json is written on first boot with every toggle on:

{
  "event_quests": true,
  "daily_givers": true,
  "bounty_board": true
}

Set one to false and restart or run /snpc questhost reload to leave that capability to Endless Leveling. Host state is stored under questhost/ (bounty_board.json, daily_givers.json, event_quests.json, migrated.json). On the first claim of each capability, Endless Leveling's exported director state is imported once.

/snpc questhost choose <npc> <row> is the player verb that dialogue rows run. It only acts on the caller's own open conversation.

Director settings

The directors are tuned in Endless Leveling's quests.json (config.events, config.daily_givers, config.bounties). Scuffed NPCs reads those sections and uses these values when a key is absent:

A finished but unclaimed bounty stays claimable from the journal for 24 hours after its board window ends.

World quests

Wild quest givers appear near players and ask for an elite pack to be cleared. The giver, dialogue, credit and expiry are Scuffed NPCs. The quest definition and rewards are Endless Leveling's, and the elites come from endless-elite-mobs. Both must be installed and new enough. When one is missing the boot log says worldquest: director is OFF and names what is absent. /snpc worldquest list repeats that report.

Pacing is a per-player offer clock. A player becomes due again offerGapSeconds after their last offer, or firstOfferDelaySeconds after the director first sees them. At most one site stands up per director tick, in the world with the most overdue player. Nothing about a site is persisted, and the director deletes every world_* custom quest at boot.

Commands

All except accept are staff only and in-game only.

worldquests.json

Seeded with defaults when missing. Every key falls back to its default on its own, so a bad edit costs one setting.

The old keys spawnEverySeconds, playersPerQuest and minActivePerWorld are retired and ignored.

Templates are picked by weight. Fields: id, name, weight, countMin, countMax, mobClass (an endless-elite-mobs class name, empty for a natural roll), tierBonus (rungs above the level-derived tier), rewardMultiplier, lifetimeExempt, rearm, roles, rewardCommands and rewards.

{
  "id": "hunt", "name": "Hunt", "weight": 4,
  "countMin": 3, "countMax": 5, "mobClass": "",
  "tierBonus": 0, "rewardMultiplier": 1.0,
  "lifetimeExempt": false, "rearm": false,
  "roles": ["Trork_Warrior", "Trork_Hunter", "Outlander_Brute",
            "Outlander_Berserker", "Goblin_Scrapper", "Skeleton_Fighter"],
  "rewardCommands": [],
  "rewards": ["common_augment_reroll"]
}

rewards are Endless Leveling rewards.json bundle ids paid on turn-in, [] disables them, and rewardCommands are console commands bundled per site. With rearm false (the default) a dead pack is not mustered again for a later hunter. With true, each later accepter gets a fresh pack until maxCompletionsPerSite. lifetimeExempt sites ignore lifetimeSeconds.

The shipped boss template is one BOSS-class elite, tierBonus 1 and rewardMultiplier 2.0, with roles Trork_Warrior, Outlander_Brute and Skeleton_Knight. Base rewards per tier (before the multiplier): XP 1500, 3000, 5000, 8000, 12000, 18000 for E to S; a floor of 6, 8, 10, 12, 15 and 18 percent of the claimer's next-level XP (sent to Endless Leveling as xp_level_percent); essence 1, 1, 2, 2, 3, 4.

Sites also refuse ground inside a guild claim and inside ScuffedProtection claims that deny the quest-npcs region flag.

Mob safety (mobsafety.json) and /snpc orphans

Hostiles spawned by quests (world-quest elites and rescue attackers) and whatever they summon carry an snpc- spawn lineage. They are never saved to disk and are swept when their owner ends. mobsafety.json is written with every key on first boot (and rewritten once if keys are missing):

These work from the console or by an op or scuffednpcs.admin player.

Guild workers

Worker NPCs (miner, harvester, builder, training dummy) are guild-only and need EndlessGuilds. Hiring is charged to the guild bank. Rank checks use the leader, co-leader and officer ranks.

Items

There is no crafting recipe for the placed blocks. Give them to players with your item tools, shops or rewards:

Worksite and altar interactions respect cancelled place, break and use events from protection plugins.

Staff commands

/snpc workersadmin subcommands, /snpc blessing give|take|pool|list and /snpc orphans accept the console. Blessing ids are ZBEVE, ENKI, HERMES, TYCHE, HEPHAESTUS and ATLAS. The cost aliases are /snpc costs and /snpc blessings.

Hire costs and the kill switch

Balance levers (worker_balance.json)

The balancing console edits live values and saves a flat map of lever id to number. Defaults:

Movement levers (miner.move_base, move_per_tier, and the same for builder and harvester) default to 1.0 and 0.0. Station times are 12, 15, 20, 20, 30 and 40 minutes for Copper, Iron, Cobalt, Thorium, Adamantite and Mithril (mining levers cover the yields). worker_tools.json stores per type and tier held-tool overrides, set on the Tools page. The default curves are pickaxe, sickle and hammer from Crude, Copper, Iron to Steel.

Other worker files

Blueprints and build projects

Builders place blueprints from the prefab catalog or from guild-sold builds. Materials come from chests, and every placement and chest access is checked against EndlessGuilds, ScuffedProtection, WorldProtect, OrbisGuard and SimpleClaims as the guild's current leader.

Files: prefab_config.json (per prefab: buyable, price, display name), guild_blueprints.json (owned blueprints), guild_prefab_market.json (submissions and sales), guild_prefabs/ (captured builds), build_jobs.json (projects).

While a player is in blueprint selection mode, the mod grants them the engine permission hytale.editor.selection.use temporarily, together with a tagged Selection Tool. It is revoked on exit, submit, disconnect and by a periodic sweep, and any stray tool is reclaimed at next login.

Thief goblins

thief_goblins.json is created on first boot and read at boot only.

{
  "enabled": true,
  "spawnIntervalSeconds": 120.0,
  "spawnChance": 0.25,
  "areaCooldownSeconds": 600.0,
  "maxPerWorld": 8,
  "chestRadius": 32.0,
  "despawnDistance": 96.0,
  "despawnGraceSeconds": 15.0,
  "excludedWorlds": []
}

A value outside its range makes the plugin refuse to load, so keep edits inside the table. Worlds with NPC spawning disabled, creative players and dead players do not trigger raids. /snpc test thief spawns one goblin 6 to 10 blocks away, aimed at the nearest stocked container within chestRadius, ignoring spawn rolls, exclusions and cooldowns. It still obeys the per-world maximum, roof and ground checks.

Eggplant Galore event

/snpc event opens the event picker and the Eggplant Galore console. State is stored in event.json (with a .bak), and payout progress in event_payouts.txt.

Event defaults (editable in the console):

Keys are granted through BetterLootBox, including to offline players. Guild levels are granted through EndlessGuilds. Each reward line is journaled after it succeeds, so re-running Pay Winners after a restart skips what was already granted.

Prologue tutorial (Tutorial V2)

The mod ships a prologue campaign for Endless Leveling servers (prologue_v2): 23 required steps and 11 optional ones with a Guide, a Guild Registrar, an Auctioneer and a Guild Master, a Mournhollow catacombs run, and steps that depend on Endless Leveling, Fates, Rifts, Guilds, EndlessLink and ZenShop. The definition is inside the jar. A builder places it on the server with the setup commands.

At boot it registers the whole campaign with Endless Leveling in one call. If Endless Leveling lacks both the batch and the per-step registration methods, or refuses any step, the steps already registered are taken back and the older campaign keeps running. If Endless Leveling is not ready yet, activation is retried every 2 seconds for up to 10 minutes. It also writes the campaign's reward bundles into Endless Leveling when they differ. The mod has no setting to switch the campaign off, so a server that does not want it should not pair this mod with an Endless Leveling build that accepts runtime campaign registration.

Default world aliases are hub = AdventurersGuild, mournhollow = instance-mournhollow-shared and open = endless. Builder choices are saved in tutorial_points.json (previous copy kept as .bak; a file that cannot be read is never overwritten, and setup refuses changes until it is fixed). Player progress is in tutorial_state.json. Lines that still read PLACEHOLDER: are counted by the readiness check.

Campaign helpers

These commands support the older built-in campaign (Act 0 to 2) and are staff only:

Captured points are stored in campaign_points.json. Per-player campaign flags are in campaign_flags.json, and parked guides in parked_guides.json.

Instance stories

Party-aware story characters for instanced dungeons are driven by other mods through InstanceStoryApi (see below). Four bundled scripts ship (breach_outlander, breach_undead, breach_void, breach_infernal) plus nine sky_* scripts. Copies are written to stories/ when missing; the disk copy wins. A disk copy with an older version than the jar's is moved to <id>.json.v<n>.bak and reseeded. Any other *.json in stories/ is loaded as an extra story whose file name must equal its id.

These work from the console or by staff. A file story_selftest.txt in the data folder listing script ids (or all) runs the same test once at boot and is then deleted.

Permissions

Scuffed NPCs defines one permission node and uses the built-in operator group.

Player-facing commands are gated by guild rank, not by nodes: /snpc workers, /snpc projects and the blueprint shop need the guild leader, co-leader or officer rank (or staff). Selling a blueprint is open to any guild member.

Four read-only or authoring helpers (/snpc cost list, /snpc path list, /snpc path cancel and /snpc dialogueanims) take the same op or scuffednpcs.admin check on builds after 1.98.34.

Staff commands run from the console are accepted for the console-capable groups noted above (workersadmin roster commands, blessing give|take|pool|list, story, orphans, debug). The /snpc quests, bounty, worldquest, questhost, tutorial and most other commands are in-game only.

Other staff commands

Advanced JVM properties: scuffednpcs.dialogue.cps (default typing speed), scuffednpcs.dialogue.playerPortraits (false turns off live player-head portraits), scuffednpcs.dialogue.lockinput, and scuffednpcs.eldialogues (explicit path to campaign_dialogues.json).

Data & storage

All files are in mods/Zbeve_ScuffedNPCs/. Hand-authored files are restored from the jar only when missing.

The mod also keeps small marker components on NPC entities (SCNPCID, SCWORKERID) so it can re-link NPCs that the engine restores with their chunk.

Integrations

Quest providers are wired by reflection and retried every 30 seconds for up to 15 minutes if a provider loads late. The mod registers no PlaceholderAPI placeholders and does not call an economy API directly: money is moved through the guild bank (workers, blueprints) or through the console commands in bounty pools and rewards.

API for other mods

All entry points are static, use JDK and engine types only, never throw, and are meant to be reached by reflection.

com.zbeve.scuffednpcs.ScuffedNPCsApi

com.zbeve.scuffednpcs.api.DialogueHostApi (API_VERSION 1) lets another mod write an NPC's conversation and have it shown in the Scuffed NPCs dialogue page. register(prefix, host) hosts every npcKey starting with the prefix (longest prefix wins). The host is a BiFunction<UUID, String, String> called on the player's world thread with a JSON request {"npc","action","speaker"} and returning JSON {"speaker","tag","body","rows":[{"id","label","kind"}],"close"}. Row kinds are offer, more, leave, quest, track, done and claim, with up to six rows. open(player, npcKey) and openAt(player, npcKey, speakerName, x, y, z) open the page, and isAvailable() and unregister(prefix) complete it. Pressing F on a matching NPC opens the hosted page and nothing else.

com.zbeve.scuffednpcs.api.InstanceStoryApi (API_VERSION 1) runs party-aware story characters in instance worlds: isAvailable, hasScript, registerScript(id, json) (in memory only, bundled ids refused), startRun(world, scriptId, party, points, vars), addPartyMember, removePartyMember, fire(runId, key, uuid), setListener(runId, listener), flag, payout, endRun(runId, success), plus the cutscene helpers moveCharacter, releaseCharacter, setSceneHold, setLeadTarget and clearLeadTarget. Story keys in include player_joined, intro_done, section_armed:<k>, section_cleared:<k>, boss_engaged, boss_defeated, wipe and beat:<k>. Events out are flag, objective, say and talk. Each live step becomes an Endless Leveling instance quest under the provider id scuffednpcs_stories.

Troubleshooting