NPC Overlay

NPC Overlay — published listing 1.0.0

Show a name or role above an NPC when a player approaches. The plugin does not create NPCs, open Dialogs or track quests. The Codefling listing says 1.0.0; its current download identifies itself as NpcOverlay 1.0.1. Check the installed plugin before following this guide.

Edit the overlay data

The configurator edits oxide/data/NpcOverlay.json. A new file has no NPC entries.

1. In Overlays, add a setting named with the real NPC UserIDString supplied by your NPC plugin.
2. Set LangKey to a language key, for example npc.bob.role. This is not the text players will see.
3. Adjust Color and LocalOffset, then export the file. A new entry defaults to yellow, one world unit above the NPC; verify its colour and position in game.

Example of the exported entry — use your actual NPC ID:

{
  "Overlays": {
    "REPLACE_WITH_REAL_NPC_ID": {
      "LangKey": "npc.bob.role",
      "Color": { "r": 1, "g": 1, "b": 0, "a": 1 },
      "LocalOffset": { "x": 0, "y": 1, "z": 0 }
    }
  }
}

Keep a copy of the old data file before replacing it. Exporting does not change your server automatically.

Add the matching text in the server’s NpcOverlay language file, for example oxide/lang/en/NpcOverlay.json:

{ "npc.bob.role": "Quest giver" }

Use the framework-managed language file shown above, not oxide/data/lang. The key must match LangKey exactly. Add translations to each language you support.

Provider and runtime checks

Your NPC provider must send the proximity hooks with the NPC and player BasePlayer objects. This release subscribes to OnEnterNPC and OnExitNPC, but names its leaving handler OnLeaveNPC. That mismatch can prevent labels from being removed. Test both entering and leaving on a private server before live use.

Back up the data and language files, reload the plugin, then verify the text, colour, position, language and label removal. Validation in the configurator checks the file structure, not whether your NPC provider works correctly in game.