Skip to content

ApiVisualEffects

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.

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)

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.

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

Values:

  • Alpha
  • Additive

Values:

  • Red
  • Green
  • Blue
  • Alpha

Values:

  • Four
  • Eight
  • Twelve
  • Sixteen

Values:

  • Constant
  • Decay
  • Swell
  • Pulse

Values:

  • Linear
  • Smooth
  • EaseIn
  • EaseOut
NameValueDescription
Poison1c419034-7c0f-4e65-a3af-81f27a1e0efaCreeping green at the edges of the screen.
Bleed0e778268-d89d-4538-80c6-621ca768a4b2Red streaks running in from the edges.
Fog7195989d-5c02-47b8-bcd9-b91aaaafaa99Drifting grey haze over the whole view.
Drunk271f1b8f-13b1-4a4a-acc4-a9784852398bSlow swimming blur, with the centre wandering.
Concussionb7b6a46c-9899-4d6f-8493-cd22d695c0fbHard jolt: a shake, a flash of blur and colour fringing.
TunnelVisionb006e04f-3087-4ac7-bdbb-0c903d35792dThe view closes in to a narrow circle.
Deathbd6cf532-4dc4-46d7-94eb-bc061ef041daEverything drains and darkens.
Desaturate3f2a9c41-5b8e-4c17-9d60-7ae4c2b8f153The whole view drained of colour, evenly. Nothing else.
EarthquakeRumble7f67a87a-e30a-441b-9b5a-3a91da98d050Sustained low rumble. Shake only - nothing is drawn.

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.


(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.9
handle = API.VisualEffects.Start(effect, 5)

Parameters:

NameTypeOptionalDescription
idstring❌ NoThe composition’s id, from GetProfiles or Ids.

Return Type: ApiEffectProfile - The copy.

Raises:

  • ArgumentException - The ID is malformed or was not found

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, 0
effect.AddLayer(tint)
handle = API.VisualEffects.Start(effect, 4)

Return Type: ApiEffectProfile - The composition, with the client’s own fade timing and no layers.


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.


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.


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.


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.


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.


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.


Build a standalone screen shake, for StartShake.

Example:

shake = API.VisualEffects.NewShakeConfig()
shake.Seconds = 2.5
shake.Intensity = 0.8
shake.Gradient = API.VisualEffects.ShakeGradient.Decay
API.VisualEffects.StartShake(shake)

Return Type: ApiShakeConfig - The shake.


(x, y) Build a per-axis value pair, for the visual effect knobs that take one.

Parameters:

NameTypeOptionalDescription
xdouble✅ YesThe X component.
ydouble✅ YesThe 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:

NameTypeOptionalDescription
profileIdstring❌ NoThe composition’s id, from GetProfiles or Ids.
secondsdouble✅ YesHow long to run for. Zero or less runs until stopped; capped at 86400.
intensitydouble✅ YesStrength 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, or seconds or intensity is 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:

NameTypeOptionalDescription
configApiEffectProfile❌ NoThe composition to draw. Needs at least one and at most four layers.
secondsdouble✅ YesHow long to run for. Zero or less runs until stopped; capped at 86400.
intensitydouble✅ YesStrength 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 - config has 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.

(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:

NameTypeOptionalDescription
namestring❌ NoThe composition’s name, matched ignoring case. Must match exactly one.
secondsdouble✅ YesHow long to run for. Zero or less runs until stopped; capped at 86400.
intensitydouble✅ YesStrength 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, or seconds or intensity is not a real number.

(handle) Stop one visual effect this script started. It fades out rather than cutting.

Parameters:

NameTypeOptionalDescription
handleuint❌ NoThe 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)


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)


(config) Shake the screen, with no visual effect attached.

Example:

shake = API.VisualEffects.NewShakeConfig()
shake.Seconds = 0.4
shake.Intensity = 1.0
API.VisualEffects.StartShake(shake)

Parameters:

NameTypeOptionalDescription
configApiShakeConfig❌ NoThe 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 on config is not one of the options the API offers, or one of its values is not a real number.
  • ArgumentOutOfRangeException - config.Seconds is zero or less. A shake needs a length - there is nothing that would end an open-ended one.

(handle) Stop one screen shake this script started.

Parameters:

NameTypeOptionalDescription
handleuint❌ NoThe 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)


Stop every screen shake this script started, including the ones its visual effects fired as they arrived.

Return Type: void (Does not return anything)