Dynamic Item Icon 1.0.0

Custom & animated item icons, rendered server-side

Give any item on your server a custom or animated icon — rendered server-side, streamed to players, no client mods needed.

DynamicItemIcon repaints the icons of any item — vanilla items pulled from the CDN, Workshop skins fetched straight from Steam, or your own PNG files — and animates them right on the server. Effects, presets, keyframe clips and per-frame rendering all run off-thread, so your TPS won't feel it.

22 effects  11 presets  30+ API methods  25 commands  zero config

   Features

• Any icon, any source
  Vanilla items · Workshop skins by ID · your own PNG files
  Every icon streams to players as a server-side sprite — nothing to install on the client.
• Effect chain language
  Chain effects with commas, tune each with named args: fx=glitch:3,neon:0x00ffcc
  From invert to pixelsort — 22 built-in effects, stacks compose freely.
• 11 ready presets
  corrupted · cursed · retro · golden · frozen · cartoon · vhs · cyber · void · holo · inferno
  One name — a tuned stack of effects. Mix presets into chains as building blocks.
• Keyframe clips
  Author animations as keyframe timelines:
  Per-key effect clips · frame indices · 5 easing types · loop / once / ping-pong
• Persistent bindings
  A bound animation rests on its frame 0 — players see the animated icon immediately on relog, dedup per session.
• Warm cache
  Frame-0 icons regenerate instantly at wipe/recompile — no cold stutter.
  Cache invalidation tracks code edits via IL-signature + MVID.
• Compositing
  Stack layers from item, skin or crc sources.
  5 blend modes — over · add · multiply · screen · subtract — plus per-layer fx and opacity.
• CustomItemDefinitions support
  Overrides sprites for custom items out of the box.
• Batch export
  di.batchfx <png> runs any PNG through all 22 effects and 11 presets in one shot.
  34 PNG files written to disk — preview every look before you bind.
• Targeted export & hue recolors
  di.exportfx rifle.ak hueshift:60 hueshift:120 — each fx argument lands as its own PNG file.
  one command → many variants for icon packs and skin shops.
• Wipe-safe
  OnNewSave clears state, icons restore at next boot.
  Atomic writes · debounced saves · data files stay clean.

Installation

1. Drop DynamicItemIcon.cs into your plugins/ folder.
2. Get a GSLT token (required for Workshop skin sources): log in at steamcommunity.com/dev/managegameservers, create a token for App ID 252490 (Rust).
3. Add it to your launch script:

+server.login_token <YOUR_TOKEN>

Restart the server. The token is read once at Steam login — a hot reload will not pick up a newly added launch argument.

Start adding icons: di.skin <workshopId> to preview a Workshop skin, di.fx rifle.ak invert to test an effect.

Steam auth fallback: token missing or invalid → the plugin still boots with a warning, server stays on anonymous login; Workshop fetching degrades gracefully to the vanilla icon. Vanilla icons and your own PNGs work without any token.

For developers

30+ API methods, all callable from other plugins:

• Fetch & process: API_GetSkinIcon, API_GetItemIcon, API_ProcessSkinIcon, API_ProcessItemIcon, API_ProcessItem
• Composite: API_CompositeIcon, API_CompositeItem
• Animate: API_AnimateItem, API_PlayClip, API_BindClip, API_BindAnimation, API_UnbindAnimation, API_StopAnimation, API_StopAllAnimations
• Author clips: API_RecordClip (×2 variants), API_DeleteClip
• Register effects/presets: API_RegisterEffect (×2, owned), API_RegisterPreset (×2)
• Query: API_GetCRC, API_GetStoredIcons, API_ListEffects, API_ListPresets, API_ListClips, API_ListAnimations

Admin commands

25 console commands under di.*:

• Items & skins: di.item, di.skin, di.fx, di.skinfx, di.processitem, di.compose
• Registry: di.effects, di.icons
• Animations: di.animate, di.animbind*, di.animstop, di.animlist, di.warmbind
• Clips: di.cliprecord, di.cliprecordkeys, di.clipplay, di.clipbind, di.cliplist, di.clipshow, di.clipdelete
• Exports: di.batchfx <png> — every effect, di.exportfx <png> <fx...> — targeted variants

Permissions

dynamicitemicon.admin — grants the full di.* command set.

Configuration

Deliberately minimal: one config option. Zero-config by design — everything interesting is done over the API and commands.

Data lives under data/DynamicItemIcon/: processed/, vanilla/, skinned/, batch/ and export/.

Compatibility & limits

• Source fetches time out and fall back to the vanilla icon — a failed download never bricks your items.
• Effect owners pause/resume cleanly: owner plugin unloads → its bound animations keep playing from cache.
• Max 1024 animation frames per clip; client preload throttled (≈40 PNG/s) so relogs don't spike players.

FAQ

Do players need to install anything?
No — icons are server-rendered PNGs streamed through Rust's native icon pipeline.

Will it break my server without the Steam token?
No — falls back to anonymous login with a warning; only Workshop fetching degrades.

What happens after a wipe?
Bindings clear on the new save, cached icons restore automatically at boot.

Does it lag the server?
Frame generation and PNG encoding run on the thread pool; the main thread only decodes the source once.

Can other plugins add effects?
Yes — API_RegisterEffect accepts their own delegates; ownership tracking handles their reloads.

Support & credits

Written by 0xF. Join https://discord.gg/8nztXhvgDe for support and updates.