Skip to content

Troubleshooting

This page covers common issues with NPC citizens and how to resolve them.

Symptoms: The NPC does not appear in the world. /kscitizen list shows a red dot next to the citizen ID.

Possible Causes:

  1. Wrong world — The NPC’s world must be loaded. Check the citizen’s worldName: since Core 2.8.0 world names match exactly (default no longer matches default_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.

  2. hideNpc is enabled — If hideNpc: true is 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
  3. 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.

  4. 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.

  5. 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.

  6. The NPC file failed to load — Core keeps a broken citizens.json or custom_citizens*.json, makes a .corrupt-<time> copy and writes nothing to it. The hub’s Status tab and /kscitizen reload name locked files. Fix the JSON and run /kscitizen reload.

  7. 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.

Symptoms: The NPC appears with a default skin, no skin at all, or is invisible.

Solutions:

  1. Verify the skin username — The skinUsername field 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"
  2. 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>
  3. 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.

  4. isPlayerModel mismatch — If isPlayerModel is false but no entityTypeId is set, the NPC may not have a visible model. Set either:

    "isPlayerModel": true, "skinUsername": "SomeName"

    or:

    "isPlayerModel": false, "entityTypeId": "Trork_Guard"

Symptoms: Pressing F on the NPC does nothing, or the dialog does not open.

Check these:

  1. fKeyInteractionEnabled must be true — Without this, the “Press F” prompt does not appear.

    "fKeyInteractionEnabled": true
  2. Quest NPC Profile conflict — If the Quest mod has a profile for this citizen, it intercepts the dialog. The citizen’s own dialogs array is ignored when a quest profile exists.

  3. All conditions fail — If all entries in the dialogs array 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" }
    ]
    }
  4. Dialog file missing — The referenced dialogId must exist as a JSON file in mods/kyuubisoft_core/dialogs/. Check the console for Dialog not found warnings, or run “Check” in the dialog editor.

  5. Invalid startNode — The dialog file must have a valid startNode that references an existing node in the nodes array.

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.

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:

  1. Respawn the NPC — Run /kscitizen respawn <id> to force a clean spawn.
  2. 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.

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:

  1. 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).

  2. Verify the citizen’s worldName — The marker system only shows markers for citizens whose worldName matches the player’s current world. Check that the value matches exactly; instance copies (instance-Forgotten_Temple-<id>) match their template name Forgotten_Temple.

  3. Check the server console — Look for registration messages like MarkerProvider registered on world: Forgotten_Temple.

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:

  1. Respawn the NPC — Run /kscitizen respawn <id>.
  2. Check the movement type — Make sure the movementType is valid (IDLE, WANDER, etc.). An invalid value defaults to IDLE.

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:

  1. Reload citizens — /kscitizen reload despawns all citizens and their holograms, then respawns fresh.
  2. Respawn specific NPC — /kscitizen respawn <id> for a single NPC.
  3. Automatic cleanup — The system tracks hologram entity UUIDs and removes old ones on spawn. If you encounter persistent duplicates, a full reload resolves it.

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.

Many NPCs in one area:

  • Each NPC with PROXIMITY animations checks player distances every 500ms. With many NPCs and many players, this can add up.
  • Consider increasing proximityRange values or reducing animation frequency (interval) for NPCs in dense areas.

Skin fetching:

  • Each unique skinUsername needs 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.