API Troubleshooting

NPC does not show up

Common reasons:

• The NPC is disabled and the viewer is not OP / doesn’t have npc.admin.
  • Fix: npc.setEnabled(true) or test as OP.
• Player is in another world.
  • showNPCToPlayer(...) will hide the NPC if the player world differs.
• The NPC’s chunk is not loaded.
  • showNPCToPlayer(...) exits early if the chunk is not loaded.

Option changes don’t apply

• If you created NpcAPI with new NpcConfig().autoUpdate(false), then setOption(...) won’t push packets.
  • Fix: call npc.reload().
  • Or enable autoUpdate(true).

Skins do not update

• Skin changes often require a reload to resend player info packets.
• Mojang fetch can fail (rate limit / offline / invalid name). Always handle Optional.empty().

Pathfinding fails

PathfindingUtils.findPath(...) can throw PathfindingException if a segment can’t be found.

• Fix: ensure waypoints are walkable and not inside blocks.
• Increase maxIterations for harder paths.

I see errors on startup/shutdown

• Ensure you call NpcApi.disable() in onDisable().
• If you have multiple plugins shading NpcAPI, avoid classpath conflicts.

Saving fails with NotSerializableException

• npc.save() also serializes the click handler (NpcClickAction).
• Avoid lambdas that capture plugin instances or other non-serializable objects.