Icons Plugin

QuestLines Icons

Floating per-player quest-state icons that appear above NPCs. At a glance, players can see whether an NPC has a new quest for them, a quest in progress, all quests completed, or a repeatable quest on cooldown.

How It Works

QuestLines Icons reads NPC quest assignments from QuestLines’ mods/QuestLines/npcs.json and displays a floating item above each NPC. The icon shown is determined per player based on their quest state for the quests assigned to that NPC. Icons are updated on every server tick and are invisible to players who are not in range.

ℹ
Requires QuestLines Core

Icons reads quest assignments directly from QuestLines’ npcs.json. QuestLines Core must be installed and configured for Icons to show anything.

Quest States

Each NPC is evaluated against the player’s quest data to determine which state to show. States are resolved in priority order: the highest-priority state that applies wins.

State Key Default Icon Default Animation Description
Available available Icons_Exclamation Ping + Bob The NPC has a quest the player has not yet started.
In Progress inprogress Icons_Dots Rotate The player has the quest and it is currently in progress.
Completed completed Icons_Checkmark Rotate The player has completed every quest this NPC offers.
Waiting waiting Icons_Clock Bob Quest is repeatable and the player is waiting for the repeat condition.
Unknown unknown Icons_QuestionMark Orbit Quest state is not yet resolved for this player / NPC pair.

Commands

All configuration is done via /icons (alias: /i) using a wand-style workflow: run the command, then click an NPC in-world to apply the setting.

Command Description
/icons reload Reload icons.json and re-sync NPC assignments from npcs.json.
/icons icon <itemId> Click an NPC to set its floating icon item. Use none to disable the icon for that NPC entirely.
/icons offset <offset> Click an NPC to set the Y-offset of its icon in blocks (e.g. 0.5 to raise it). Default is 0.0.
/icons scale <scale> Click an NPC to set the icon scale multiplier (e.g. 1.5 for 50% larger). Default is 1.0.
/icons rotation <degrees> Click an NPC to set a fixed Y-axis rotation for the icon in degrees. Default is 0.
/icons animate <animation> [state] Click an NPC to apply an animation. Optionally target a specific quest state (e.g. available). See Animations for format.
/icons list List all NPC IDs that have explicit icon configuration in icons.json.

Animations

Animations are applied via /icons animate <animation>. Multiple animation types can be active simultaneously on the same NPC icon. Each animation takes an optional speed and amplitude parameter.

Animation Format Speed Amplitude Description
bob bob[:speed[:amp]] Hz (cycles/sec) Max Y displacement (blocks) Bobs the icon up and down.
rotate rotate[:speed] Degrees/sec — Continuously spins the icon on the Y axis.
pulsate pulsate[:speed[:amp]] Hz Max scale delta added to base scale Smoothly oscillates the icon’s size.
sway sway[:speed[:amp]] Hz Max rotation in degrees Rocks the icon side-to-side on the Z axis.
orbit orbit[:speed[:amp]] Hz Orbit radius (blocks) Circles the icon horizontally around the NPC.
ping ping[:speed[:amp]] Hz (pops/sec) Max scale delta per pop Brief sharp scale pop — attention-grabbing.
ring ring[:speed[:amp]] Hz (burst freq) Max lateral displacement (blocks) Rapid side-to-side shake in periodic bursts.
float float[:speed[:amp]] Hz Drift radius (blocks) Organic figure-8 Lissajous XZ drift.
stamp stamp[:speed[:amp]] Hz (stamps/sec) Drop distance (blocks) Periodic sharp downward drop; idles high.
none none or none:<type> — — Clears all animations, or clears only the specified type.

Animation Examples

// Bob at default speed (1 Hz) and amplitude (0.2 blocks)
/icons animate bob

// Spin at 90 degrees per second
/icons animate rotate:90

// Orbit slowly at 0.5 Hz with a 1.5-block radius
/icons animate orbit:0.5:1.5

// Ping animation only on the "available" state icon
/icons animate ping:0.5:0.4 available

// Remove only the rotate animation
/icons animate none:rotate

// Clear all animations
/icons animate none
💡
Tip: State-targeted animations

Add an optional state name after the animation to apply it only when the icon is showing that quest state — e.g. /icons animate ping:0.5:0.4 available. This lets you have the “available” icon draw more attention than the “completed” one.

Configuration File

All icon settings are persisted in mods/QuestLinesIcons/icons.json. You can edit this file directly or use the /icons commands to update it in-game. Below is the full structure. 

{
  // Global fallback item shown on any NPC that has no per-NPC override
  "DefaultIconItemId": "Recipe_Page",
  "DefaultIconOffset":  0.0,

  // Global item overrides per quest state (used for all QuestLines NPCs)
  "DefaultQuestStateIcons": {
    "available":  "Icons_Exclamation",
    "inprogress": "Icons_Dots",
    "completed":  "Icons_Checkmark",
    "waiting":    "Icons_Clock",
    "unknown":    "Icons_QuestionMark"
  },

  // Global default animations per quest state
  "DefaultQuestStateAnimations": {
    "available": {
      "ping": { "speed": 0.5, "amplitude": 0.4 },
      "bob":  { "speed": 0.5, "amplitude": 0.12 }
    }
  },

  // Per-NPC item override (any item ID or "none" to disable)
  "NpcQuestIcons": {
    "citizen_42": "Custom_Star",
    "citizen_07": "none"
  },

  // Per-NPC per-state item overrides
  "NpcQuestIconStates": {
    "citizen_42": {
      "available": "Icons_Exclamation",
      "completed": "Icons_Checkmark"
    }
  },

  // Per-NPC Y-offsets in blocks
  "NpcQuestIconOffsets": {
    "citizen_42": 0.5
  },

  // Per-NPC scale multipliers
  "NpcQuestIconScales": {
    "citizen_42": 1.25
  },

  // Per-NPC fixed Y rotation in degrees
  "NpcQuestIconRotations": {
    "citizen_42": 45.0
  },

  // Per-NPC animations (multiple types active at once)
  "NpcAnimations": {
    "citizen_42": {
      "bob":    { "speed": 1.0, "amplitude": 0.2 },
      "rotate": { "speed": 60.0, "amplitude": 0.0 }
    }
  },

  // Per-NPC per-state animation overrides
  "NpcStateAnimations": {
    "citizen_42": {
      "available": {
        "ping": { "speed": 0.5, "amplitude": 0.3 }
      }
    }
  }
}

Configuration Override Priority

When determining which icon and animation to show for a given NPC and player, the plugin uses the following priority chain:

Icon item

  1. Per-NPC entry in NpcQuestIcons (static override, ignores quest state)
  2. Per-NPC per-state entry in NpcQuestIconStates for the player’s current state
  3. Global per-state entry in DefaultQuestStateIcons
  4. Built-in default for the state (e.g. Icons_Exclamation for available)

Animation

  1. Per-NPC per-state entry in NpcStateAnimations
  2. Global per-state entry in DefaultQuestStateAnimations
  3. Built-in defaults per state (see Quest States table above)
  4. Per-NPC entry in NpcAnimations (NPC-level, state-agnostic)

Permissions

Permission Default Description
icons.admin false Required for all /icons commands.