@color-matrix applies a color-grading filter to a specific sprite or to everything visible in the scene at once. You reach for it whenever a moment needs a shift in mood without swapping any assets - dimming and desaturating a rainy alley at 3 a.m., washing a memory sequence in pale warmth, or snapping a portrait to high contrast during a tense reveal.

The construct transitions smoothly from the scene's current color state to the values you specify, so you can chain calls back to neutral just as naturally as you pushed away from it. The canonical example above shows this rhythm: push the whole frame into a cold, dim look before the line lands, then ease it back out to signal the moment passing.

When target is empty, the filter lands on the in-world frame, which means UI elements like dialogue boxes are unaffected. If you name a sprite tag instead, only that sprite's colors shift while the rest of the scene stays put - useful for spotlighting one character without touching the background or other sprites on stage.

Hue rotation wraps at the 360-degree boundary, so a transition from 350 to 10 will travel the long way around the color wheel unless you plan the sequence carefully. If you need the short arc, keep rotations within a single crossing of zero.

Setting wait to false lets you layer a color shift under a say verb or another effect without stalling the script. Be cautious about firing a second @color-matrix on the same target before the first finishes - the new call interrupts from wherever the filter sits at that instant, not from your intended baseline. If you need a clean starting point, send an explicit reset to defaults before beginning the next transition.