ApiVisualEffects
Class Description
Section titled “Class Description”On-screen visual effects and screen shake, reached through API.VisualEffects.
Starting an effect hands back a handle, which is what stops it early. A handle of 0 means nothing
was raised: the system is off, you are not in the world, or scripts already hold every slot -
SlotsFree tells those apart.
Nothing you raise outlives your script. Whatever is still running when it stops is dropped, as is everything on leaving the world. Getting a setting wrong raises an error instead, since that is a mistake in the script rather than a state of the client.
Properties
Section titled “Properties”Enabled
Section titled “Enabled”Type: bool
Whether the user has full-screen visual effects switched on. They ship off, and a script
cannot override that - Start answers 0 while this is false.
Example:
if API.VisualEffects.Enabled: API.VisualEffects.Start(API.VisualEffects.Ids.Poison, 3)ShakeEnabled
Section titled “ShakeEnabled”Type: bool
Whether the user has screen shake switched on. As with visual effects it ships off and a
script cannot override it - StartShake answers 0 while this is false.
The setting alone, so it can read true while StartShake still answers 0: shake also
needs you in the world. SlotsFree is what tells those apart - it answers 0 out of
world too.
SlotsFree
Section titled “SlotsFree”Type: int
How many more effects every script on the client may raise between them, and 0 while you are not in the world. Shared rather than per script, so a script holding effects it no longer needs takes them from the others - stop what you are done with.
Example:
h = API.VisualEffects.Start(API.VisualEffects.Ids.Fog, 10)if not h and API.VisualEffects.SlotsFree == 0: API.SysMsg("another script is using every effect slot")OverlayBlend
Section titled “OverlayBlend”Values:
AlphaAdditive
NoiseChannel
Section titled “NoiseChannel”Values:
RedGreenBlueAlpha
OverlaySampleTaps
Section titled “OverlaySampleTaps”Values:
FourEightTwelveSixteen
ShakeGradient
Section titled “ShakeGradient”Values:
ConstantDecaySwellPulse
ShakeCurve
Section titled “ShakeCurve”Values:
LinearSmoothEaseInEaseOut
Constants
Section titled “Constants”| Name | Value | Description |
|---|---|---|
Poison | 1c419034-7c0f-4e65-a3af-81f27a1e0efa | Creeping green at the edges of the screen. |
Bleed | 0e778268-d89d-4538-80c6-621ca768a4b2 | Red streaks running in from the edges. |
Fog | 7195989d-5c02-47b8-bcd9-b91aaaafaa99 | Drifting grey haze over the whole view. |
Drunk | 271f1b8f-13b1-4a4a-acc4-a9784852398b | Slow swimming blur, with the centre wandering. |
Concussion | b7b6a46c-9899-4d6f-8493-cd22d695c0fb | Hard jolt: a shake, a flash of blur and colour fringing. |
TunnelVision | b006e04f-3087-4ac7-bdbb-0c903d35792d | The view closes in to a narrow circle. |
Death | bd6cf532-4dc4-46d7-94eb-bc061ef041da | Everything drains and darkens. |
Desaturate | 3f2a9c41-5b8e-4c17-9d60-7ae4c2b8f153 | The whole view drained of colour, evenly. Nothing else. |
EarthquakeRumble | 7f67a87a-e30a-441b-9b5a-3a91da98d050 | Sustained low rumble. Shake only - nothing is drawn. |
Methods
Section titled “Methods”GetProfiles
Section titled “GetProfiles”List the visual effect compositions this client knows about, shipped and user-authored.
Example:
for info in API.VisualEffects.GetProfiles(): API.SysMsg(f"{info.Name} -> {info.Id}")Return Type: IList<ApiEffectProfileInfo> - The library, in the order the options list it.
GetProfile
Section titled “GetProfile”(id)
Get an editable copy of one of the client’s visual effect compositions, as a starting point
for a variation on it. The copy is yours - changing it does not touch the client’s, and there
is no way to save it back.
Example:
effect = API.VisualEffects.GetProfile(API.VisualEffects.Ids.Poison)effect.Layers[0].Effect.Strength = 0.9handle = API.VisualEffects.Start(effect, 5)Parameters:
| Name | Type | Optional | Description |
|---|---|---|---|
id | string | ❌ No | The composition’s id, from GetProfiles or Ids. |
Return Type: ApiEffectProfile - The copy.
Raises:
ArgumentException- The ID is malformed or was not found
NewProfile
Section titled “NewProfile”Build an empty visual effect composition, to add layers to with AddLayer.
Example:
effect = API.VisualEffects.NewProfile()tint = API.VisualEffects.NewTintLayer()tint.R, tint.G, tint.B = 150, 0, 0effect.AddLayer(tint)handle = API.VisualEffects.Start(effect, 4)Return Type: ApiEffectProfile - The composition, with the client’s own fade timing and no layers.
NewTintLayer
Section titled “NewTintLayer”Build a color layer, set to the client’s defaults. The only technique that paints rather than distorting, and so the only one that may sit anywhere in a stack.
Like every layer, it costs a full-screen pass per frame while the effect runs.
Return Type: ApiTintLayer - The layer.
NewBlurLayer
Section titled “NewBlurLayer”Build a disk blur layer, set to the client’s defaults. Out-of-focus vision.
The priciest technique: a full-screen pass per frame, at Taps samples per pixel.
Return Type: ApiBlurLayer - The layer.
NewRadialBlurLayer
Section titled “NewRadialBlurLayer”Build a zoom blur layer, set to the client’s defaults. Reads as vertigo rather than poor focus, because the centre of the screen stays sharp however strong it is.
A full-screen pass per frame, at Taps samples per pixel.
Return Type: ApiRadialBlurLayer - The layer.
NewChromaticLayer
Section titled “NewChromaticLayer”Build a chromatic split layer, set to the client’s defaults. The cheapest technique by a wide margin - three samples per pixel - so it is worth reaching for first when something needs to look wrong.
Return Type: ApiChromaticLayer - The layer.
NewSaturationLayer
Section titled “NewSaturationLayer”Build a saturation layer, set to the client’s defaults - fully drained to grey. Raise
Saturation toward 1 for a partial drain, past 1 to push the colour past its real value.
One sample per pixel: the cheapest technique that reads the frame at all.
Return Type: ApiSaturationLayer - The layer.
NewShakeSpec
Section titled “NewShakeSpec”Build the shake a visual effect fires as it arrives, to hang on ApiEffectProfile.Shake. For
a shake on its own use NewShakeConfig instead.
Return Type: ApiShakeSpec - The shake, set to the client’s defaults - an impact that decays.
NewShakeConfig
Section titled “NewShakeConfig”Build a standalone screen shake, for StartShake.
Example:
shake = API.VisualEffects.NewShakeConfig()shake.Seconds = 2.5shake.Intensity = 0.8shake.Gradient = API.VisualEffects.ShakeGradient.DecayAPI.VisualEffects.StartShake(shake)Return Type: ApiShakeConfig - The shake.
NewVector2
Section titled “NewVector2”(x, y)
Build a per-axis value pair, for the visual effect knobs that take one.
Parameters:
| Name | Type | Optional | Description |
|---|---|---|---|
x | double | ✅ Yes | The X component. |
y | double | ✅ Yes | The Y component. |
Return Type: ApiVector2 - The pair.
(profileId, seconds, intensity)
Start one of the client’s visual effect compositions by id.
A composition raised this way claims the look against the rulebase, so starting poison while the player is poisoned shows one poison rather than two at doubled alpha.
Effects do not survive leaving the world: the handle goes stale and nothing comes back on the next login. Stop them yourself, give them a duration, or let the script end - whatever a script leaves running is dropped when it stops.
Example:
handle = API.VisualEffects.Start(API.VisualEffects.Ids.Drunk, 10)API.Pause(2)API.VisualEffects.Stop(handle)Parameters:
| Name | Type | Optional | Description |
|---|---|---|---|
profileId | string | ❌ No | The composition’s id, from GetProfiles or Ids. |
seconds | double | ✅ Yes | How long to run for. Zero or less runs until stopped; capped at 86400. |
intensity | double | ✅ Yes | Strength to draw at, 0-1. Scales the composition rather than replacing anything in it. |
Return Type: uint - A handle for Stop, or 0 if the user has visual effects switched off, you are not in the world, or every slot is in use.
Raises:
ArgumentException- The ID is not in the right format, no effect in the client has it, orsecondsorintensityis not a real number.
(config, seconds, intensity)
Start a visual effect the script built itself.
Unlike the two by-name forms this claims nothing, because there is no library composition
behind it to claim - so two scripts starting identical hand-built effects do composite
together, at doubled strength. Editing config afterwards cannot reach the running effect;
start it again to change it.
Parameters:
| Name | Type | Optional | Description |
|---|---|---|---|
config | ApiEffectProfile | ❌ No | The composition to draw. Needs at least one and at most four layers. |
seconds | double | ✅ Yes | How long to run for. Zero or less runs until stopped; capped at 86400. |
intensity | double | ✅ Yes | Strength to draw at, 0-1. |
Return Type: uint - A handle for Stop, or 0 if the user has visual effects switched off, you are not in the world, or every slot is in use.
Raises:
ArgumentException-confighas no layers or more than four, one of its layers is empty, a setting is not one of the options the API offers, or a value is not a real number.
StartByName
Section titled “StartByName”(name, seconds, intensity)
Start one of the user’s own visual effect compositions by name.
User-authored compositions only. Every shipped one is named through the client’s language file
and carries a “(built-in)” suffix, so no name here could reach them on a non-English client -
use Start with Ids for those.
Parameters:
| Name | Type | Optional | Description |
|---|---|---|---|
name | string | ❌ No | The composition’s name, matched ignoring case. Must match exactly one. |
seconds | double | ✅ Yes | How long to run for. Zero or less runs until stopped; capped at 86400. |
intensity | double | ✅ Yes | Strength to draw at, 0-1. |
Return Type: uint - A handle for Stop, or 0 if the user has visual effects switched off, you are not in the world, or every slot is in use.
Raises:
ArgumentException- You have no effect with that name, several of yours share it, orsecondsorintensityis not a real number.
(handle)
Stop one visual effect this script started. It fades out rather than cutting.
Parameters:
| Name | Type | Optional | Description |
|---|---|---|---|
handle | uint | ❌ No | The handle a Start returned. Handles that already lapsed, were stopped, came back as 0, or belong to another script are ignored. |
Return Type: void (Does not return anything)
StopAll
Section titled “StopAll”Stop every visual effect this script started. Other scripts’ effects, and the ones the player’s own state raises, are left alone.
Return Type: void (Does not return anything)
StartShake
Section titled “StartShake”(config)
Shake the screen, with no visual effect attached.
Example:
shake = API.VisualEffects.NewShakeConfig()shake.Seconds = 0.4shake.Intensity = 1.0API.VisualEffects.StartShake(shake)Parameters:
| Name | Type | Optional | Description |
|---|---|---|---|
config | ApiShakeConfig | ❌ No | The shake to run, from NewShakeConfig. |
Return Type: uint - A handle for StopShake, or 0 if the user has screen shake switched off or you are not in the world.
Raises:
ArgumentException- A setting onconfigis not one of the options the API offers, or one of its values is not a real number.ArgumentOutOfRangeException-config.Secondsis zero or less. A shake needs a length - there is nothing that would end an open-ended one.
StopShake
Section titled “StopShake”(handle)
Stop one screen shake this script started.
Parameters:
| Name | Type | Optional | Description |
|---|---|---|---|
handle | uint | ❌ No | The handle StartShake returned. Handles that already finished, were stopped, came back as 0, or belong to another script are ignored. |
Return Type: void (Does not return anything)
StopAllShakes
Section titled “StopAllShakes”Stop every screen shake this script started, including the ones its visual effects fired as they arrived.
Return Type: void (Does not return anything)