Particle Systems and Shader Effects in G.js

G.js exposes first-class support for Geometry Dash’s particle systems and the post-processing shader effects introduced in GD 2.2. Particles let you build visual flourishes like snow, fire, sparks, and explosions directly in JavaScript, while shaders allow you to apply screen-wide filters — sepia, chromatic aberration, glitch, and more — on the fly using trigger wrappers that return standard GJsObject values.

Particle Systems

A particle system in GD is a special object that continuously emits configurable sprites. G.js wraps the full particle system object so you can construct one with a plain JavaScript dictionary of properties, position it with .with(), and place it in your level with .add().

`particle_system()`

particle_system(props, use_obj_color?, animate_on_trigger?, animate_active_only?, quick_start?)

Creates a particle system object and returns a GJsObject. Chain .with() calls to position or configure it, then call .add() to place it in the level.

Parameter	Type	Default	Description
`props`	`object`	—	Dictionary of particle properties (see below)
`use_obj_color`	`boolean`	`false`	Use the object’s own color channel instead of per-particle RGBA
`animate_on_trigger`	`boolean`	`false`	Only start emitting when an Animate trigger targets this object
`animate_active_only`	`boolean`	`false`	Makes `animate_on_trigger` apply only while the object is active
`quick_start`	`boolean`	`false`	Achieve normal particle movement instantly rather than gradually

Particle Properties (`particle_props`)

The particle_props dictionary maps every particle field name to its internal GD property index. Pass these keys in the props argument to particle_system().

Import particle_props and use it as a reference or for dynamic lookups. When calling particle_system() you pass the key names directly as a plain object literal — you do not need to reference particle_props numerically yourself.

Property	Description
`MAX_PARTICLES`	Maximum number of live particles at once
`DURATION`	How long the system runs (`-1` = infinite)
`LIFETIME`	Lifetime of each particle in seconds
`LIFETIME_VAR`	Random variance added/subtracted from lifetime
`EMISSION`	Emission rate in particles/second (`-1` = max)
`ANGLE`	Direction particles emit (degrees)
`ANGLE_VAR`	Variance in emission angle
`SPEED`	Speed of emitted particles
`SPEED_VAR`	Variance in particle speed
`POSVAR_X`	Spawn area width variance on the X axis
`POSVAR_Y`	Spawn area height variance on the Y axis
`GRAVITY_X`	Gravity along the X axis
`GRAVITY_Y`	Gravity along the Y axis
`ACCEL_RAD`	Radial acceleration
`ACCEL_RAD_VAR`	Radial acceleration variance
`ACCEL_TAN`	Tangential acceleration
`ACCEL_TAN_VAR`	Tangential acceleration variance
`START_SIZE`	Initial particle size
`START_SIZE_VAR`	Initial size variance
`START_SPIN`	Initial spin (degrees)
`START_SPIN_VAR`	Initial spin variance
`START_R`	Initial red channel (0–1)
`START_R_VAR`	Initial red variance
`START_G`	Initial green channel (0–1)
`START_G_VAR`	Initial green variance
`START_B`	Initial blue channel (0–1)
`START_B_VAR`	Initial blue variance
`START_A`	Initial alpha/opacity (0–1)
`START_A_VAR`	Initial alpha variance
`END_SIZE`	Final particle size
`END_SIZE_VAR`	Final size variance
`END_SPIN`	Final spin
`END_SPIN_VAR`	Final spin variance
`END_R`	Final red channel
`END_R_VAR`	Final red variance
`END_G`	Final green channel
`END_G_VAR`	Final green variance
`END_B`	Final blue channel
`END_B_VAR`	Final blue variance
`END_A`	Final alpha
`END_A_VAR`	Final alpha variance
`FADE_IN`	Fade-in duration
`FADE_IN_VAR`	Fade-in duration variance
`FADE_OUT`	Fade-out duration
`FADE_OUT_VAR`	Fade-out duration variance
`START_RAD`	Initial radial position
`START_RAD_VAR`	Initial radial position variance
`END_RAD`	Final radial position
`END_RAD_VAR`	Final radial position variance
`ROT_SEC`	Rotation per second
`ROT_SEC_VAR`	Rotation per second variance
`GRAVITY_RADIUS`	Radius for gravity effect
`FREE_RELATIVE_GROUPED`	Particle movement mode (free / relative / grouped)
`ADDITIVE`	Enable additive blending for a glow look
`START_SPIN_END`	Use initial spin value at end
`START_ROT_IS_DIR`	Use initial rotation as emission direction
`DYNAMIC_ROTATION`	Apply dynamic rotation
`TEXTURE`	Particle texture ID
`UNIFORM_OBJ_COLOR`	Uniform object color flag
`FRICTION_P`	Parallel friction
`FRICTION_P_VAR`	Parallel friction variance
`RESPAWN`	Particle respawn rate
`RESPAWN_VAR`	Respawn rate variance
`ORDER_SENSITIVE`	Order-sensitive rendering
`START_SIZE_END`	Use start size at end
`START_RAD_END`	Use start radial position at end
`START_RGB_VAR_SYNC`	Sync initial RGB variances
`END_RGB_VAR_SYNC`	Sync final RGB variances
`FRICTION_S`	Perpendicular friction
`FRICTION_S_VAR`	Perpendicular friction variance
`FRICTION_R`	Rotational friction
`FRICTION_R_VAR`	Rotational friction variance

Basic Example — Glowing Particle Burst

The following example is adapted directly from the G.js README and creates a simple glowing white particle effect:

import '@g-js-api/g.js';

await $.exportConfig({ type: 'savefile', options: { info: true } });

particle_system({
  MAX_PARTICLES: 30,
  DURATION: -1,
  LIFETIME: 1,
  LIFETIME_VAR: 0.3,
  EMISSION: -1,
  ANGLE: 90,
  ANGLE_VAR: 90,
  SPEED: 29,
  POSVAR_X: 11,
  START_SIZE: 2,
  START_SIZE_VAR: 1,
  END_SIZE: 1,
  END_SIZE_VAR: 1,
  START_R: 1,
  START_G: 1,
  START_B: 1,
  START_A: 1,
  END_R: 1,
  END_G: 1,
  END_B: 1,
  END_A: 1,
  ADDITIVE: true
})
  .with(obj_props.X, 200)
  .with(obj_props.Y, 100)
  .add();

Snow Effect Example

Here is a more complete example that creates a falling-snow particle system with slight horizontal drift:

import '@g-js-api/g.js';

await $.exportConfig({ type: 'savefile', options: { info: true } });

// Assign a group so we can reference the system later
let snowSystem = unknown_g();

particle_system({
  MAX_PARTICLES: 80,
  DURATION: -1,       // run forever
  LIFETIME: 3,
  LIFETIME_VAR: 0.8,
  EMISSION: -1,       // emit at max rate
  ANGLE: 270,         // downward
  ANGLE_VAR: 20,      // slight spread
  SPEED: 40,
  SPEED_VAR: 10,
  POSVAR_X: 200,      // spread across wide horizontal band
  POSVAR_Y: 5,
  GRAVITY_Y: -5,      // gentle downward pull
  START_SIZE: 3,
  START_SIZE_VAR: 1.5,
  END_SIZE: 1,
  END_SIZE_VAR: 0.5,
  START_R: 1,
  START_G: 1,
  START_B: 1,
  START_A: 0.9,
  END_R: 1,
  END_G: 1,
  END_B: 1,
  END_A: 0,           // fade out as they fall
  ADDITIVE: false
}, false, true)       // animate_on_trigger = true
  .with(obj_props.X, 300)
  .with(obj_props.Y, 250)
  .with(obj_props.GROUPS, snowSystem)
  .add();

`spawn_particle()`

spawn_particle(
  particle_group,
  pos_group?,
  offset_x?,
  offset_y?,
  scale?,
  scale_var?,
  rotation?,
  rotation_var?,
  offvar_x?,
  offvar_y?,
  match_rot?
)

The Spawn Particle trigger places an instance of a particle system at a target location at runtime. This is useful for one-shot bursts like explosions or impact effects — the particle system object itself does not need to be visible.

Parameter	Type	Default	Description
`particle_group`	group	—	Group ID of the particle system to spawn
`pos_group`	group	—	Target location group; particles spawn at that object’s position
`offset_x`	`number`	`0`	Additional X offset from the target position
`offset_y`	`number`	`0`	Additional Y offset from the target position
`scale`	`number`	`1`	Scale multiplier for the spawned system
`scale_var`	`number`	`0`	Random variance added to scale
`rotation`	`number`	`0`	Rotation in degrees applied to the system
`rotation_var`	`number`	`0`	Random rotation variance
`offvar_x`	`number`	`0`	Randomize spawn area on X axis
`offvar_y`	`number`	`0`	Randomize spawn area on Y axis
`match_rot`	`boolean`	`false`	Match rotation of nearby particles

// Spawn a particle burst at a player-touched object
let explosion = unknown_g();
let target_marker = unknown_g();

on(touch(), trigger_function(() => {
  spawn_particle(explosion, target_marker, 0, 0, 1.2);
}));

Shader Effects (GD 2.2)

GD 2.2 introduced screen-space post-processing shaders that can be activated via triggers. G.js wraps each shader as a function that returns a GJsObject — you call .add() on the result to insert the trigger into your level. All shader triggers accept a strength and an optional duration.

Shader triggers affect the entire screen. The duration parameter (default 0) controls how long the effect lasts; 0 means it persists until another shader trigger overrides it.

Available Shaders

Function	Signature	Description
`sepia`	`sepia(strength, duration?)`	Warm sepia color filter
`hue_shift`	`hue_shift(shift, duration?)`	Rotate hue 0–360 degrees
`grayscale`	`grayscale(strength, duration?)`	Desaturate to grayscale
`pixelate`	`pixelate(strength, duration?)`	Block-pixel mosaic effect
`chromatic`	`chromatic(strength, duration?)`	Chromatic aberration (RGB fringing)
`glitch`	`glitch(strength, duration?)`	Digital glitch distortion
`bulge`	`bulge(strength, duration?)`	Fisheye/bulge lens distortion
`split_screen`	`split_screen(strength, duration?)`	Split-screen duplication effect

All strength values are in the range 0–1 unless noted. hue_shift takes a degree value (0–360).

`shader_layers()` and `shader_layer()`

For advanced compositions, GD supports layered shaders where each layer contributes its own strength.

shader_layer(layer, strength)  // create a single layer entry (layer: 0–15, strength: 0–1)
shader_layers(layers)          // create a shader layers trigger from an array of shader_layer values

shader_layer() returns a string (a layer descriptor), while shader_layers() returns a GJsObject that must have .add() called on it.

Individual Shader Examples

import '@g-js-api/g.js';

await $.exportConfig({ type: 'savefile', options: { info: true } });

// Apply a full-strength sepia filter that fades over 2 seconds
sepia(1.0, 2).add();

Combined Chromatic + Glitch Effect

Triggering multiple shaders at the same time creates a layered visual effect. The following example fires a chromatic aberration and glitch combo when the player touches a trigger zone:

import '@g-js-api/g.js';

await $.exportConfig({ type: 'savefile', options: { info: true } });

on(touch(), trigger_function(() => {
  // Hit both shaders simultaneously — they each last 1 second
  chromatic(0.8, 1).add();
  glitch(0.5, 1).add();
}));

Layered Shader Example

import '@g-js-api/g.js';

await $.exportConfig({ type: 'savefile', options: { info: true } });

// Compose two shader layers — layer 0 at 80% strength, layer 1 at 40%
shader_layers([
  shader_layer(0, 0.8),
  shader_layer(1, 0.4),
]).add();

Keyframe Animations

Animate objects across position, rotation, and scale using keyframe sequences.

Camera & Visual

Control the camera with offsets, zoom, rotation, and free mode.

Shaders API Reference

Full API reference for all shader functions.

General Purpose API

Reference for particle_system, spawn_particle, and other general-purpose triggers.

Get Started

Core Concepts

Guides

Particle Systems and Shader Effects in G.js