   🔵 Discord     ☕ Ko-fi     ⭐ Patreon     📖 Wiki  

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).

QuestLines Icons