Troubleshooting
This page covers common issues with NPC citizens and how to resolve them.
NPC Not Spawning
Section titled “NPC Not Spawning”Symptoms: The NPC does not appear in the world. /kscitizen list shows a red dot next to the citizen ID.
Possible Causes:
-
Wrong world — The NPC’s world must be loaded. Check the citizen’s
worldName: since Core 2.8.0 world names match exactly (defaultno longer matchesdefault_flat); instance copies still match their template name. Core logs a one-time warning for NPCs whose world name only matched under the old partial rule. -
hideNpcis enabled — IfhideNpc: trueis set in the config (or the NPC was hidden in the NPC window), the NPC is intentionally hidden. A schedule can also hide it at day or night."hideNpc": false -
Invalid NPC role — The citizen’s movement and interaction settings determine which NPC role is used internally. If the role does not exist, spawning fails silently. Check the server console for warnings like
NPC Role not found. -
Invalid position — The coordinates might be inside a block or outside the loaded area. Try teleporting to the position with
/kscitizen tp <id>to verify. -
Missing skin — For player model NPCs, if the skin cannot be fetched (bad username, timeout), the NPC may appear invisible. Check the server console for skin fetch errors.
-
The NPC file failed to load — Core keeps a broken
citizens.jsonorcustom_citizens*.json, makes a.corrupt-<time>copy and writes nothing to it. The hub’s Status tab and/kscitizen reloadname locked files. Fix the JSON and run/kscitizen reload. -
Nobody is near yet — Right after a start, or where no player is near, the NPC’s area is loaded but not active yet, and the game keeps the NPC stored there. Core waits until a player comes near and then takes over the NPC that is already there.
Wrong Skin or Invisible NPC
Section titled “Wrong Skin or Invisible NPC”Symptoms: The NPC appears with a default skin, no skin at all, or is invisible.
Solutions:
-
Verify the skin username — The
skinUsernamefield must be a valid Hytale player name. The skin is fetched from an online skin database. An NPC with a skin from the in-game skin editor (customSkin) uses that instead."skinUsername": "SomePlayer" -
Skin cache — Skins are cached. If a player changed their skin, run
/kscitizen skinreload <id>: it uses the current skin of that player if they are online, otherwise it fetches the skin again./kscitizen skinreload <id> -
Skin prefetch timeout — On server start, all skins are prefetched with a 30-second timeout. If many NPCs need fresh skins and the API is slow, some may fail. The console will show
Skin prefetch timed out. -
isPlayerModelmismatch — IfisPlayerModelisfalsebut noentityTypeIdis set, the NPC may not have a visible model. Set either:"isPlayerModel": true, "skinUsername": "SomeName"or:
"isPlayerModel": false, "entityTypeId": "Trork_Guard"
Dialog Not Working
Section titled “Dialog Not Working”Symptoms: Pressing F on the NPC does nothing, or the dialog does not open.
Check these:
-
fKeyInteractionEnabledmust betrue— Without this, the “Press F” prompt does not appear."fKeyInteractionEnabled": true -
Quest NPC Profile conflict — If the Quest mod has a profile for this citizen, it intercepts the dialog. The citizen’s own
dialogsarray is ignored when a quest profile exists. -
All conditions fail — If all entries in the
dialogsarray have conditions that do not match, no dialog opens. Add a fallback entry without a condition at the end:{"dialogs": [{ "dialogId": "special", "condition": { "type": "quest_completed", "value": "q1" } },{ "dialogId": "default_greeting" }]} -
Dialog file missing — The referenced
dialogIdmust exist as a JSON file inmods/kyuubisoft_core/dialogs/. Check the console forDialog not foundwarnings, or run “Check” in the dialog editor. -
Invalid startNode — The dialog file must have a valid
startNodethat references an existing node in thenodesarray.
Nameless NPC Copies After a Restart
Section titled “Nameless NPC Copies After a Restart”Symptoms: Several copies of an NPC stand on the same spot, some without name and skin (“KS NPC Interactable Role”). The log showed Failed to spawn citizen … (NPCPlugin returned null).
Cause: Before Core 2.9.4, Core did not see an NPC that the game kept stored in an area that was not active yet. It spawned a new one, and every try left another copy that was saved with the world.
Solution: Update Core. Core now waits until the area is active and takes over the NPC that is already there. To remove copies from earlier starts, open the NPC viewer (/kscitizen viewer or the /ksadmin hub), go to Orphaned and press “Clean up orphans”. Otherwise Core removes an orphan by itself about 10 seconds after someone enters its world, as the viewer notes for each one. See NPC Viewer.
Double Nametags
Section titled “Double Nametags”Symptoms: The NPC shows two name labels — one from the vanilla nameplate system and one from the hologram system.
Cause: The vanilla Hytale nameplate system adds a default nametag based on the NPC role’s NameTranslationKey. The KyuubiSoft system uses its own hologram-based nametags for better control.
Solution: This is handled automatically. The system clears the vanilla nameplate text on spawn. If you still see double nametags:
- Respawn the NPC — Run
/kscitizen respawn <id>to force a clean spawn. - Check for chunk persistence — If the server was stopped during development, stale entity data in chunk files can cause duplicates. A reload fixes this:
/kscitizen reload
The hologram cleanup system automatically removes duplicate holograms when citizens are reattached after a chunk reload. If you see duplicates after a world change or relog, they should resolve within a few seconds.
Markers Not Showing on All Worlds
Section titled “Markers Not Showing on All Worlds”Symptoms: World map markers (quest ! and ? icons) appear in the default world but not in other worlds like Forgotten_Temple.
Cause: The WorldMap MarkerProvider must be registered on every world. Registration happens automatically when a player enters a world via the AddPlayerToWorldEvent.
Solutions:
-
Enter the world first — Markers only appear after at least one player has entered the world in the current server session. The provider registration is lazy (on-demand).
-
Verify the citizen’s
worldName— The marker system only shows markers for citizens whoseworldNamematches the player’s current world. Check that the value matches exactly; instance copies (instance-Forgotten_Temple-<id>) match their template nameForgotten_Temple. -
Check the server console — Look for registration messages like
MarkerProvider registered on world: Forgotten_Temple.
NPC Walks Away During Dialog
Section titled “NPC Walks Away During Dialog”Symptoms: A wandering NPC keeps walking while you are in a dialog or shop interaction.
This should not happen. The system automatically freezes wandering NPCs when a player interacts with them. The NPC’s movement is paused and it turns to face the interacting player. When the dialog or shop is closed, movement resumes.
If the NPC still moves:
- Respawn the NPC — Run
/kscitizen respawn <id>. - Check the movement type — Make sure the
movementTypeis valid (IDLE,WANDER, etc.). An invalid value defaults toIDLE.
Hologram Duplication
Section titled “Hologram Duplication”Symptoms: Multiple floating nametags stack above an NPC, or old nametags remain after editing.
Cause: Hologram entities from a previous server session can persist in chunk data. When the NPC is respawned, new holograms are created without cleaning up the old ones.
Solutions:
- Reload citizens —
/kscitizen reloaddespawns all citizens and their holograms, then respawns fresh. - Respawn specific NPC —
/kscitizen respawn <id>for a single NPC. - Automatic cleanup — The system tracks hologram entity UUIDs and removes old ones on spawn. If you encounter persistent duplicates, a full reload resolves it.
NPC Takes Damage
Section titled “NPC Takes Damage”Symptoms: Players or mobs can damage or kill the NPC.
Solution: Set both damage flags in the citizen config:
{ "takesDamage": false, "invulnerable": true}takesDamage: false— Prevents damage at the plugin level.invulnerable: true— Adds the Invulnerable component at the engine level.
If respawnOnDeath is true, the NPC will respawn after respawnDelay seconds even if killed.
Performance Considerations
Section titled “Performance Considerations”Many NPCs in one area:
- Each NPC with
PROXIMITYanimations checks player distances every 500ms. With many NPCs and many players, this can add up. - Consider increasing
proximityRangevalues or reducing animation frequency (interval) for NPCs in dense areas.
Skin fetching:
- Each unique
skinUsernameneeds one online lookup on first use. Skins are cached after the first fetch. - The prefetch system loads all skins on server start (30-second timeout). For servers with many NPCs, ensure good network connectivity.
World map markers:
- Markers use a view-distance check. Only markers within the player’s map view range are sent. This scales well even with hundreds of NPCs.