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 progress:
- Exclamation mark — quest available
- Dots — quest in progress
- Checkmark — quest completed
- Question mark — unknown state
- Per-state overrides:
- Set different icons per quest state per NPC
- Apply animations per state or globally
- Developer API — implement
QuestStatusProvider to feed quest states from any plugin
- 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.
| Command | Description |
|---|
/icons icon [--itemid <itemId>] [--state <state>] | Set the NPC's icon. Omit --itemid to use your held item. none hides it, default resets it. Use --state to target a specific quest state. |
/icons offset --offset <value> | Set the vertical position of the icon above the NPC. |
/icons scale --scale <value> | Set the icon's scale. 1.5 = 50% larger, etc. |
/icons rotation --degrees <degrees> | Set a fixed Y-axis rotation in degrees. |
/icons animate --animation <animation> [--state <state>] | Add or remove an animation. Use --state to apply it to a specific quest state. |
/icons list | List every NPC that has an icon configured. |
/icons reload | Reload icons.json without restarting. |
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. But if you want to hand-edit it, run /icons reload afterward and it'll pick up the changes.
{
"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 needed, 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 they only see the correct one.
If you're not using QuestLines, you can still feed quest-state data from your own plugin by implementing the QuestStatusProvider interface and calling NpcQuestIconsPlugin.getInstance().setQuestStatusProvider(provider).
