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.

Color channels are the way Geometry Dash controls the color of objects and the environment at runtime. Every channel has a numeric ID, and triggers written to that channel affect all objects using it. G.js wraps each channel in a $color instance that exposes every color-related trigger as a method, so you can drive dynamic lighting, flashing effects, and timed fades with plain JavaScript — no raw trigger dictionaries required. For a conceptual overview see Groups, Colors & Blocks.

​
Creating Colors

​
color(id)

Creates a $color instance from a known color channel ID. G.js marks this ID as in-use so it will not be returned by unknown_c(). 
const my_color = color(5);
my_color.set([255, 100, 0], 0.5);
​
id
number
required
The GD color channel ID.
Returns $color

​
unknown_c()

Allocates and returns the next free color channel ID. Use this when you need a channel but do not care about its exact number. 
const flash_color = unknown_c();
Returns $color

​
new $color(a, specific?)

The underlying class constructor. Prefer color() and unknown_c() in everyday code; use the constructor when you need explicit control over ID allocation.
​
a
number
required
The color channel ID value.
​
specific
boolean
default:"true"
When true (the default), marks this ID as unavailable for future unknown_c() allocations.
$color is also a named TypeScript export for use in type annotations: 
import { $color } from '@g-js-api/g.js/safe';

function fadeToBlack(c: $color, duration: number) {
  c.set([0, 0, 0], duration);
}

​
Pre-defined Color Constants

G.js exposes named constants for the special built-in GD color channels. Import them from @g-js-api/g.js/safe in safe mode; they are available globally otherwise.
ConstantChannel
BGBackground
GROUNDGround (layer 1)
GROUND2Ground (layer 2)
LINEGround line
_3DLINE3D line
OBJECTDefault object color
MIDDLEGROUNDMiddleground layer 1
MIDDLEGROUND_2Middleground layer 2
BLACKPure black channel
WHITEPure white channel
LIGHTERLighter color channel
BG.set([20, 20, 60], 1);       // dark blue background
GROUND.set([10, 10, 40], 1);   // matching ground

​
Methods

​
set(c, duration?, blending?)

Creates a Color trigger that sets the channel to an RGB value.
​
c
number[]
required
Target RGB color as a three-element array, e.g. [255, 128, 0]. Use the rgb() helper for a named alternative.
​
duration
number
default:"0"
Seconds over which the color transitions to c.
​
blending
boolean
default:"false"
When true, enables additive blending on the color channel.
// Instant red
BG.set([255, 0, 0]);

// Slow fade to sky blue
BG.set(rgb(100, 180, 255), 2);

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

Creates a Copy Color trigger that mirrors another channel, optionally with an HSV transform applied on top.
​
c
$color
required
The source color channel to copy from.
​
duration
number
default:"0"
Transition duration in seconds.
​
hvs
string
default:"\"0a1a1a0a0\""
HSV modifier string. Use the hsv() helper to generate this value cleanly.
​
blending
boolean
default:"false"
Enable additive blending on the destination channel.
​
opacity
number
default:"1"
Opacity of the copied color (0–1).
​
copy_opacity
boolean
default:"false"
When true, also copies the source channel’s opacity value.
const target = color(10);
target.copy(BG, 0.5, hsv(30, 1, 1));

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

Creates a Pulse trigger that temporarily overlays an RGB color onto the channel.
​
c
number[]
required
RGB color to pulse, e.g. [255, 200, 100].
​
fade_in
number
default:"0"
Seconds to blend in the pulse color.
​
hold
number
default:"0"
Seconds to hold the pulse color at full strength.
​
fade_out
number
default:"0"
Seconds to fade back to the original color.
​
exclusive
boolean
default:"false"
When true, this pulse takes priority over other simultaneous pulses on the same channel.
const col = unknown_c();
col.pulse([255, 200, 100], 0, 0.5, 0.3);

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

Creates a Pulse trigger using HSV values rather than RGB.
​
h
number
required
Hue offset (-180 to 180).
​
s
number
required
Saturation value.
​
b
number
required
Brightness value.
​
s_checked
boolean
default:"false"
When true, saturation is treated as an absolute value rather than an offset.
​
b_checked
boolean
default:"false"
When true, brightness is treated as an absolute value rather than an offset.
​
fade_in
number
default:"0"
Fade-in time in seconds.
​
hold
number
default:"0"
Hold time in seconds.
​
fade_out
number
default:"0"
Fade-out time in seconds.
​
exclusive
boolean
default:"false"
Prioritize over simultaneous pulses on the same channel.
BG.pulse_hsv(180, 1, 1, false, false, 0.1, 0.2, 0.3);

​
Helper Functions

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

Generates an HSV modifier string for use in copy(). The string is formatted the way GD expects it internally.
​
hue
number
required
Hue offset (-180 to 180).
​
sat
number
required
Saturation value.
​
bright
number
required
Brightness value.
​
sat_checked
boolean
default:"false"
Use saturation as absolute value.
​
bright_checked
boolean
default:"false"
Use brightness as absolute value.
Returns string 
const my_hsv = hsv(30, 1.2, 0.9);
target.copy(BG, 0.5, my_hsv);

​
rgb(r, g, b)

Creates an RGB array. Equivalent to writing [r, g, b] but reads more expressively.
​
r
number
required
Red component (0–255).
​
g
number
required
Green component (0–255).
​
b
number
required
Blue component (0–255).
Returns number[]

​
rgba(r, g, b, a)

Creates an RGBA array including an alpha component.
​
r
number
required
Red component (0–255).
​
g
number
required
Green component (0–255).
​
b
number
required
Blue component (0–255).
​
a
number
required
Alpha component (0–1).
Returns number[]

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

A standalone function that creates a Color trigger without needing a $color instance. Useful when you have a raw channel ID or want a one-liner.
​
channel
$color | number
required
The color channel to target.
​
r
number
required
Red value (0–255).
​
g
number
required
Green value (0–255).
​
b
number
required
Blue value (0–255).
​
duration
number
default:"0"
Transition duration in seconds.
​
opacity
number
default:"1"
Channel opacity (0–1).
​
blending
boolean
default:"false"
Enable additive blending.
color_trigger(BG, 255, 0, 0, 1);

​
Code examples

BG.set([255, 0, 0], 0.5);
Color channel IDs in GD are limited. If you need many dynamic colors, use unknown_c() to allocate them automatically and avoid accidentally reusing channels that are already assigned to level geometry.
Modifying BG, GROUND, or other environment channels mid-level will affect the entire scene immediately. Always test timing and duration values in-game to make sure transitions look correct.

Build docs developers (and LLMs) love

Get started for freeTalk to us