Effects

import { ServerEffects, Effect } from "@sagl/server";

server.effects: the game's own particle effects, by name, and puffs of coloured dust. Each is at a spot, or on a player, ped, vehicle or object it follows. For everyone, or only to some players.

Client scripts make their own with sagl.effects.

server.effects.play(name, at, options?)

play(name: string, at: EffectTarget, options?: EffectOptions): Effect

name is one of the game's effects (its models/effects.fxp). Some of them:

Kind	Effects
Breaking	explosion_crate (wood chips), wallbust, prt_glass, prt_cardebris
Explosions	explosion_tiny, explosion_small, explosion_medium, explosion_large, explosion_molotov
Fire	fire, fire_med, fire_large, fire_car, fire_bike, molotov_flame
Smoke	smoke30m, smoke50lit, riot_smoke, teargas, BlackSmoke, WhiteSmoke
Dust, sand	dust, bigdust, heli_dust, prt_sand
Water	water_hydrant, water_fountain, water_splash, carwashspray
Sparks	prt_spark, sparks, shootlight
Other	spraycan, extinguisher, flare, cigarette_smoke, insects, flys, puke

Option	Type	Description
offset	Vector3	From what it's on (m, in its own space: y forward), or from the spot.
loop	boolean	Runs until stop() (a fire, a smoking chimney), and shows for players joining later. Default false: it plays once, as the game plays it.
to	Player[]	Who sees it. Default everyone.

Returns an Effect: stop() stops it (its last particles fade out); playing is false once stopped.

A name the game doesn't have shows nothing; the player's client logs a warning. A one-off effect whose own design loops (fire) is stopped after 15 s: give it loop to keep it going.

server.effects.play("explosion_crate", { x: 2472, y: -1670, z: 13.7 });

// A car on fire under its bonnet, until it's put out.
const fire = server.effects.play("fire", car, { loop: true, offset: { x: 0, y: 1.8, z: 0.3 } });
fire.stop();

server.effects.dust(at, options?)

dust(at: EffectTarget, options?: DustOptions): void

Puffs of the game's smoke, tinted: a Pay 'n' Spray's cloud, a car skidding on sand. They start around at and drift out and up.

Option	Type	Description
color	MapColor	0xRRGGBBAA or "#RRGGBB[AA]". Default white.
carColor	number	Instead: a colour of the game's car palette (0-127), as vehicle.colors has.
count	number	Puffs. Default 20, at most 200.
size	number	Each puff (m). Default 1.
spread	number	How far out from at they start (m). Default 1.
rise	number	How fast they drift up (m/s). Default 0.3.
life	number	How long they last, as a scale of the game's smoke. Default 1.
offset	Vector3	From what it's on, or from the spot.
to	Player[]	Who sees it. Default everyone.

// The new paint's colour, around the car.
server.effects.dust(car, { carColor: car.colors[0], count: 80, spread: 3, size: 2 });

Dust is a one-off: it isn't shown to players who join later.