GUI Animations

Version 1.4.0 added animated inventory menus. Plugins that ship animations: blocks in their menu YAML use SoapsCommon to run the effects.

You do not configure animations in SoapsCommon itself. You edit the menu file in the plugin that owns the menu (for example plugins/SoapsAdmin/gui/daily-rewards.yml).

---

Enable animations on a menu

Add an animations: section to a menu YAML file. Menus with animations use the animated screen type automatically when the owning plugin registers them that way.

Legacy animated: blocks in old menu files are converted to cycle effects on load.

---

Animation types

Set type under each animation id:

Type	Aliases	Purpose
cycle		Cycle items through states on a timer
intro		Reveal items one by one on open
shift		Move items along a path
rain		Falling particle items (loot rain effect)
roulette		Spin slots before landing on a result
click-flash	click-flash	Brief flash on click
refresh		Periodic full menu rebuild

---

Common animation keys

Key	Default	Description
type	cycle	Effect type (see table above)
interval	20	Tick interval between steps
slots	[]	Slot list for the effect
path	[]	Slot path for shift effects
columns	[]	Column slots for shift effects
materials	gold nugget, emerald, diamond	Materials for rain effect
max-row	4	Max row for rain (also max-rows, maxRows)
spawn-row	0	Where rain spawns (also spawnRow)
fall-ticks	4	Ticks per fall step (also fallTicks)
max-active	4	Max active rain items (also maxActive)
delay	2	Intro delay between items
order	slot-asc	Intro reveal order
slot	-1	Roulette center slot
trigger-item	none	Item id that starts roulette
spin-ticks	50	Roulette spin duration
flash-material	LIME_STAINED_GLASS_PANE	Click flash material
duration	4	Flash duration in ticks
sound	none	Sound on flash or roulette
interval-seconds	0	Refresh interval (refresh type)
auto-start	true	Start effect when menu opens

Roulette menus also use a pool: list of entries and optional action when the spin finishes.

---

Trigger actions from items

Use built-in actions to control animations from clickable items:

action: "[animation_trigger] daily-spin"
action: "[animation_stop] daily-spin"

The animation id must match a key under animations: in the same menu file.

---

Menu refresh field

The menu-level refresh key (seconds) rebuilds static items on a timer. This works together with animation effects. Set refresh: 0 to disable auto-refresh.

---

Performance tips

• Keep max-active low on busy menus
• Avoid many simultaneous rain effects on the same server tick
• Use settings.debug: true in the owning plugin only while testing animation timing

If animations stutter after an update, make sure SoapsCommon and the menu's plugin are on matching 1.4.x versions.