Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/g-js-api/G.js/llms.txt

Use this file to discover all available pages before exploring further.

G.js provides a complete set of wrappers around Geometry Dash’s camera and visual trigger system. Every function described in this guide emits one or more GD triggers that affect the camera, color channels, gradients, or global game state. Because these are still trigger-based, they need to be called inside a trigger function context (or at the top level before the level is exported) to take effect at the right moment during gameplay.

Camera Triggers

camera_offset(x, y, duration?, easing?)

Shifts the camera away from its default position by a fixed amount.
camera_offset(100, 50);                       // instant shift
camera_offset(-200, 0, 1.5, EASE_IN_OUT);    // smooth 1.5s pan left
x
number
Horizontal offset in GD units. Positive values move the camera right.
y
number
Vertical offset in GD units. Positive values move the camera up.
duration
number
default:"0"
Time in seconds over which the offset is applied.
easing
number
default:"NONE"
Easing constant (e.g. EASE_IN_OUT, ELASTIC_OUT). See Constants.

camera_static(gr, duration?, easing?, easing_rate?, exit_instant?, exit_static?, smooth_vel?, smooth_vel_mod?, follow?, x_only?, y_only?)

Centers the camera on a target group, optionally following it continuously.
const boss = unknown_g();

// Lock camera to boss on touch
on(touch(), trigger_function(() => {
  camera_static(boss, 0.5, EASE_IN_OUT, 0, false, false, false, 0, true);
}));
gr
$group | any
Group containing the object to center the camera on.
duration
number
default:"0"
How long the transition to the target takes.
easing
number
default:"NONE"
Easing for camera movement.
easing_rate
number
default:"0"
Rate modifier for the easing effect.
exit_instant
boolean
default:"false"
When true, exits static mode instantly.
exit_static
boolean
default:"false"
When true, cancels the static camera effect.
smooth_vel
boolean
default:"false"
Adapts the transition to the current camera velocity (no easing recommended when enabled).
smooth_vel_mod
number
default:"0"
Modifier applied to smooth velocity.
follow
boolean
default:"false"
When true, the camera tracks the object continuously rather than centering once.
x_only
boolean
default:"false"
Restrict static mode to the X axis only.
y_only
boolean
default:"false"
Restrict static mode to the Y axis only.

camera_zoom(zoom_am, duration?, easing?)

Zooms the camera in or out.
camera_zoom(2, 1.0, EASE_IN_OUT);  // zoom in to 2× over 1 second
camera_zoom(1, 0.5);               // snap back to default zoom
zoom_am
number
Zoom level. Values above 1 zoom in; values below 1 zoom out.
duration
number
default:"0"
Duration of the zoom animation.
easing
number
default:"NONE"
Easing constant for the zoom.

camera_mode(free_mode?, disable_grid_snap?, edit_cam?, easing?, padding?)

Toggles the camera’s free mode and lets you edit advanced camera settings.
camera_mode(true);                     // enable free mode
camera_mode(true, true, true, 10, 0.5); // free mode with custom easing and padding
camera_mode(false);                    // disable free mode
free_mode
boolean
default:"true"
Enable or disable free camera mode.
disable_grid_snap
boolean
default:"false"
Removes default snapping of the camera center to the nearest grid space.
edit_cam
boolean
default:"false"
Must be true for easing and padding to have any effect.
easing
number
default:"10"
Camera movement easing (requires edit_cam: true).
padding
number
default:"0.50"
Camera movement padding (requires edit_cam: true).

camera_rotate(degrees, move_time?, easing?, add?, snap360?)

Rotates the camera view.
camera_rotate(90, 0.5, EASE_IN_OUT);    // rotate 90° over 0.5s
camera_rotate(45, 0.2, NONE, true);     // add 45° to current rotation
degrees
number
Rotation amount in degrees.
move_time
number
default:"0"
Duration of the rotation animation.
easing
number
default:"NONE"
Easing constant.
add
boolean
default:"false"
When true, adds to the current camera rotation rather than setting an absolute angle.
snap360
boolean
default:"false"
Converts the rotation to the closest 360° equivalent.

camera_edge(id, edge)

Fixes one of the camera’s edges to a target object’s position. Useful for implementing custom level boundaries.
const left_wall = unknown_g();
camera_edge(left_wall, LEFT_EDGE);
id
$group | any
Group containing the object that defines the edge position.
edge
number
Which edge to set. Use one of the four edge constants:
ConstantValue
LEFT_EDGE1
RIGHT_EDGE2
UP_EDGE3
DOWN_EDGE4

Color Triggers

G.js wraps GD’s color channel system in both a functional style (color_trigger) and an object-oriented style via the $color type returned by color(id) and the built-in channel constants.

color_trigger(channel, r, g, b, duration?, opacity?, blending?)

Creates a GD color trigger and returns it as a GJsObject. Call .add() to place it in the level.
color_trigger(BG, 30, 30, 60).add();                        // dark-blue background
color_trigger(BG, 255, 100, 0, 1.0).add();                  // fade to orange over 1s
color_trigger(GROUND, 20, 20, 20, 0.5, 1.0, false).add();  // dark ground, 0.5s
channel
$color | any
The color channel to modify. Can be a channel constant (BG, GROUND, etc.) or color(n).
r
number
Red value (0–255).
g
number
Green value (0–255).
b
number
Blue value (0–255).
duration
number
default:"0"
Duration of the color transition.
opacity
number
default:"1"
Opacity (0 = transparent, 1 = opaque).
blending
boolean
default:"false"
Enables additive blending on the channel.

Color Channel Constants

The following constants are pre-defined $color instances for GD’s named channels:
ConstantDescription
BGBackground color
GROUNDGround color
LINELine color
OBJECTDefault object color
GROUND2Secondary ground color
BLACKPure black channel
WHITEPure white channel
LIGHTERLighter variant channel
MIDDLEGROUNDMiddleground color
MIDDLEGROUND_2Secondary middleground color

$color Methods

When you have a color channel variable (from color(n) or a constant like BG), you can call methods directly on it.

.set(c, duration?, blending?)

Sets the color channel to an RGB value.
BG.set(rgb(10, 10, 40));            // instant
BG.set(rgb(255, 200, 0), 1.5);     // fade over 1.5s
c
number[]
RGB array from rgb(r, g, b) or rgba(r, g, b, a).
duration
number
default:"0"
Duration in seconds.
blending
boolean
default:"false"
Enable blending.

.copy(c, duration?, hvs?, blending?, opacity?, copy_opacity?)

Copies another color channel into this one.
GROUND.copy(BG, 0.5);               // ground follows background color over 0.5s
GROUND.copy(BG, 0, hsv(30, 1, 1)); // with HSV shift
c
$color
Source color channel to copy from.
duration
number
default:"0"
Transition duration.
hvs
string
default:"\"0a1a1a0a0\""
HVS modifier string (from hsv()).
blending
boolean
default:"false"
Enable blending.
opacity
number
default:"1"
Opacity of the resulting color.
copy_opacity
boolean
default:"false"
Copy the opacity from the source channel too.

.pulse_hsv(h, s, b, s_checked?, b_checked?, fade_in?, hold?, fade_out?, exclusive?)

Pulses the channel with an HSV modifier.
BG.pulse_hsv(30, 1, 1, false, false, 0.1, 0.2, 0.1);

.pulse(c, fade_in?, hold?, fade_out?, exclusive?)

Pulses the channel to an RGB color.
BG.pulse(rgb(255, 255, 0), 0.1, 0.3, 0.2); // yellow flash

Color Helpers

hsv(hue, sat, bright, sat_checked?, bright_checked?)

Generates a GD-formatted HSV string for use with .copy() and other color operations.
const warm_shift = hsv(30, 1, 1);           // +30° hue, normal sat/bright
const desaturate = hsv(0, 0.5, 1, true);    // halve saturation

rgb(r, g, b) and rgba(r, g, b, a)

Create color arrays accepted by .set() and .pulse().
const sky_blue  = rgb(135, 206, 235);
const faded_red = rgba(255, 0, 0, 0.4);

Gradient Trigger

gradient(col, col2, bl, br, tl, tr, vertex_mode?, blending?, layer?)

Creates a GD gradient trigger and returns it as a GJsObject. Call .add() to place it.
gradient(
  color(1),   // first color channel
  color(2),   // second color channel
  group(1),   // bottom-left vertex group
  group(2),   // bottom-right vertex group
  group(3),   // top-left vertex group
  group(4),   // top-right vertex group
  true,       // vertex mode
  false,      // blending
  0           // layer 0
).add();
col
$color | any
First color channel.
col2
$color | any
Second color channel.
bl
$group | any
Bottom-left vertex group.
br
$group | any
Bottom-right vertex group.
tl
$group | any
Top-left vertex group.
tr
$group | any
Top-right vertex group.
vertex_mode
boolean
default:"true"
Use vertex mode.
blending
boolean
default:"false"
Enable blending.
layer
number
default:"0"
Gradient layer (0–15).

Time and Miscellaneous

timewarp(val)

Warps all game time by a multiplier. Values below 1 slow down the level; values above 1 speed it up.
timewarp(0.5); // slow motion
timewarp(1.0); // back to normal
timewarp(2.0); // double speed

toggle_on_trigger(group_id) and toggle_off_trigger(group_id)

Return toggle triggers as GJsObjects. Call .add() to place them.
toggle_on_trigger(group(5)).add();   // activates group 5
toggle_off_trigger(group(5)).add();  // deactivates group 5

hide_player()

Hides the player sprite. Useful for custom death or cutscene sequences.
trigger_function(() => {
  hide_player();
});

reverse()

Reverses the level direction (equivalent to a Reverse portal).
trigger_function(() => {
  reverse();
});

speed(x)

Converts a human-readable speed multiplier to the corresponding in-game speed value.
speed(1.5); // returns the GD internal value for 1.5× speed

Full Examples

Camera Follow and Zoom

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

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

const ship = unknown_g();

// Place a ship object
'ship'
  .to_obj()
  .with(obj_props.X, 300)
  .with(obj_props.Y, 200)
  .with(obj_props.GROUPS, ship)
  .add();

// When player touches, lock camera to ship and zoom in
on(touch(), trigger_function(() => {
  camera_static(ship, 0.5, EASE_IN_OUT, 0, false, false, false, 0, true);
  camera_zoom(1.5, 0.5, EASE_IN_OUT);
}));

// On release, return to default
on(touch_end(), trigger_function(() => {
  camera_static(ship, 0.3, EASE_IN_OUT, 0, false, true); // exit static
  camera_zoom(1, 0.3);
}));

Color Pulse Sequence

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

await $.exportConfig({ type: 'savefile' });

// Build a three-step color sequence on the background
const advance = sequence(
  [
    [trigger_function(() => { BG.set(rgb(255, 50, 50), 0.3); }), 1],   // red
    [trigger_function(() => { BG.set(rgb(50, 255, 50), 0.3); }), 1],   // green
    [trigger_function(() => { BG.set(rgb(50, 50, 255), 0.3); }), 1],   // blue
  ],
  MODE_LOOP
);

// Advance color on each touch
on(touch(), trigger_function(() => {
  advance();
}));

Camera Edge Boundaries

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

await $.exportConfig({ type: 'savefile' });

const left_bound  = unknown_g();
const right_bound = unknown_g();

// Place invisible boundary markers
object({ [obj_props.OBJ_ID]: 1, [obj_props.X]: 0,   [obj_props.Y]: 200, [obj_props.GROUPS]: left_bound  }).add();
object({ [obj_props.OBJ_ID]: 1, [obj_props.X]: 2000, [obj_props.Y]: 200, [obj_props.GROUPS]: right_bound }).add();

camera_edge(left_bound,  LEFT_EDGE);
camera_edge(right_bound, RIGHT_EDGE);

Events

Trigger camera changes in response to player input or position.

Control Flow

Sequence and delay visual effects over time.

Keyframes

Animate objects along keyframe paths.

General Purpose API

Full reference for camera, color, and visual trigger functions.

Build docs developers (and LLMs) love