Icons

Floating item icons above NPCs, with quest-state support.

Icons is a Hytale server plugin that floats item-entity icons above any NPC in your world. Setup is wand-style — run a command, click the NPC. No YAML hand-editing, no UUID hunting.

Features

• Float any item from your content pack above any NPC
• Per-NPC icon, vertical offset, scale and rotation
• Nine animation types, stackable on the same icon simultaneously:
  • bob — floats up and down
  • rotate — spins on the Y axis
  • pulsate — scales in and out
  • sway — rocks side to side
  • orbit — circles the NPC horizontally
  • ping — fires brief scale pops
  • ring — rapid side-to-side shake in periodic bursts
  • stamp — periodic sharp downward drop
  • float — organic figure-8
• Quest-state icons via optional QuestLines integration — each player sees a different icon based on their own progress:
  • Exclamation mark — quest available
  • Dots — quest in progress
  • Checkmark — quest completed
  • Question mark — unknown state
• Per-state overrides — different icons and animations per quest state, per NPC
• Developer API — implement QuestStatusProvider to feed quest states from any plugin
• In-game documentation — Icons registers its help pages with the in-game wiki alongside the rest of the suite
• All settings save to mods/Icons/icons.json and survive reloads

Commands

All commands have the short alias /i. Assignment commands use a wand workflow — run the command, then click an NPC.

Animation Syntax

Multiple animations can run on the same icon at the same time.

/icons animate --animation bob
/icons animate --animation bob:2:0.4
/icons animate --animation rotate:90
/icons animate --animation pulsate:1.5:0.3
/icons animate --animation sway:1:20
/icons animate --animation orbit:0.5:1.5
/icons animate --animation ping:0.5:0.5
/icons animate --animation none
/icons animate --animation none:rotate

Format: <type>[:<speed>[:<amplitude>]]

• speed — Hz for bob/pulsate/sway/orbit/ping; degrees per second for rotate
• amplitude — max displacement in blocks, degrees, or scale delta depending on type; rotate ignores this

Configuration

You shouldn't need to touch mods/Icons/icons.json directly — commands write to it automatically. If you do hand-edit it, run /icons reload afterward.

{
  "DefaultIconItemId": "Recipe_Page",
  "DefaultQuestStateIcons": {
    "available":  "Icons_Exclamation",
    "inprogress": "Icons_Dots",
    "completed":  "Icons_Checkmark",
    "unknown":    "Icons_QuestionMark"
  }
}

QuestLines Integration

Icons has a soft dependency on QuestLines. When it's present, Icons automatically shows each player a different icon above each NPC depending on their quest progress — no extra config, the four state icons ship with the content pack.

Each NPC internally maintains four icons (one per state) and the plugin filters visibility per player, so everyone sees only the correct one.

If you're not using QuestLines you can still feed quest-state data from your own plugin by implementing QuestStatusProvider and calling NpcQuestIconsPlugin.getInstance().setQuestStatusProvider(provider).

The QuestLines Suite

Every plugin works standalone; together they share one ecosystem.

• QuestLines Core — dialogue, quests, requirements, actions
• Icons — floating quest-state icons above NPCs (this plugin)
• Dialog — in-game linear dialogue builder
• Titles — player title and rank rewards
• GUI — custom in-game interfaces, no code required
• Claims — land protection, regions, rent and buy plots
• Denizens — native NPC manager
• Arcade — arcade, board and puzzle games
• Hooks — early plugin unlocking extra quest tracking
• MMO — parties, guilds, dungeons, duels and item sets
• Mimics — chests that stand up and fight
• Nations — cities and nations built on Claims (via Discord)