Troubleshooting

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

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:

1. Wrong world -- The player must be in the same world as the NPC. Check the citizen's worldName and verify you are in that world.

2. hideNpc is enabled -- If hideNpc: true is set in the config, the NPC is intentionally hidden.

   "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, API timeout), the NPC may appear invisible. Check the server console for skin fetch errors.

tip

Run /kscitizen info <id> to check the spawn status and configured role. The server console also logs detailed information during spawn attempts.

Wrong Skin or Invisible NPC

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 Minecraft username. The system fetches the skin from Mojang's API.

   "skinUsername": "Notch"

2. Skin cache -- Skins are cached on disk. If a username changed their skin, the old cached version may persist. Delete the skin cache and reload:

   /kscitizen reload

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"

Dialog Not Working

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 configs/kyuubisoft_core/dialogs/. Check the console for Dialog not found warnings.

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

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:

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

info

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

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 correctly (partial matching is supported, e.g. Forgotten_Temple matches instance-Forgotten_Temple-uuid).

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

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:

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.

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:

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.

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

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 requires an API call to Mojang on first use. Skins are cached on disk 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.