Groups, Colors, and Blocks in G.js

Geometry Dash’s runtime behavior — movement, color changes, collision detection — is driven by three kinds of numeric IDs: groups, colors, and blocks. G.js wraps each kind in a typed class ($group, $color, $block) that carries the raw ID value and exposes every corresponding trigger as an ordinary method call, so you can drive your level’s logic in plain JavaScript without ever constructing trigger dictionaries by hand.

The Three ID Types

Type	Class	Factory	Next-Free Factory
Group	`$group`	`group(id)`	`unknown_g()`
Color channel	`$color`	`color(id)`	`unknown_c()`
Collision block	`$block`	`block(id)`	`unknown_b()`

All three are exported from both the global API (import '@g-js-api/g.js') and the safe named API (import { group, color, block, ... } from '@g-js-api/g.js/safe').

Creating IDs

Known IDs — `group()`, `color()`, `block()`

Use these when you need a specific numeric ID, for example to reference a group you already placed in the GD editor.

const player_group = group(1);    // $group with ID 1
const bg_color     = color(1000); // $color with ID 1000
const hit_block    = block(1);    // $block with ID 1

Next-Free IDs — `unknown_g()`, `unknown_c()`, `unknown_b()`

Use these when you want G.js to automatically assign the next available ID. This mirrors the “Next Free” button in the GD editor and is the recommended approach for most programmatic levels.

const my_group = unknown_g(); // $group — G.js picks the next free group
const my_color = unknown_c(); // $color — G.js picks the next free color
const my_block = unknown_b(); // $block — G.js picks the next free block

The `specific` Parameter

Both factory functions accept an optional second argument specific (default true). When true, G.js marks that ID as taken and will never reuse it for an unknown_* call. Set it to false if you want to reference an ID without reserving it.

const shared_group = group(42, false); // ID 42 is still available for unknown_g()

`$group` Methods

A $group value exposes every group-targeting trigger as a method. All methods generate the appropriate GD trigger and add it to the current context automatically.

All duration and delay parameters default to 0 unless otherwise noted.

Movement

move(x, y, duration?, easing?, easing_rate?, x_multiplier?, y_multiplier?, multiply?, silent?)

void

Emits a Move trigger. x and y are in big-step GD units. Set multiply: true to convert automatically.

precise_move(x, y, duration, easing?, easing_rate?, single?)

void

Combines a Move trigger with a Follow trigger for sub-unit decimal precision (up to 2 decimal places). single saves groups and objects when the group contains only one object.

move_to(target, duration?, x_only?, y_only?, easing?, easing_rate?)

void

Move Target trigger — moves the group to the position of target group.

move_to_xy(x, y, duration?, easing?, easing_rate?)

void

Moves the group to an absolute coordinate.

follow(other, x_mod?, y_mod?, duration?)

void

Follow trigger — makes the group follow other. x_mod/y_mod scale the speed on each axis.

follow_lerp(groupA, groupB, weight?, duration?)

void

Keeps the group’s position proportionally between groupA and groupB.

follow_player_y(speed?, delay?, offset?, max_speed?, duration?)

void

Locks the group to the player’s Y axis.

lock_to_player(lock_x?, lock_y?, duration?)

void

Locks the group to the player’s position. Defaults to locking both axes for 999 seconds.

Rotation and Scale

rotate(center, degrees, duration?, easing?, easing_rate?, lock_object_rotation?)

void

Rotate trigger. center is a $group to rotate around.

scale(center, scale_x, scale_y, duration?, easing?, easing_rate?, x_divide?, y_divide?, move_only?, relative_scale?, relative_rot?)

void

Scale trigger. Set move_only: true to emulate scaling by moving instead of actually scaling.

Visibility and Alpha

alpha(opacity?, duration?)

void

Alpha trigger — changes the group’s opacity.

toggle_on()

void

Toggle On trigger.

toggle_off()

void

Toggle Off trigger.

Control Flow

call(delay?)

void

Spawn trigger — calls the group (optionally after a delay in seconds).

stop()

void

Stop trigger — stops all active triggers targeting this group.

pause()

void

Pauses the group.

resume()

void

Resumes a paused group.

Animation

animate(anim_id?)

void

Animate trigger. You can pass an animation ID directly or use the animations.[monster].[name] constants (e.g. animations.bat.idle01).

Pulse

pulse(color, fade_in?, hold?, fade_out?, exclusive?)

void

Pulse trigger with an RGB color array.

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

void

Pulse trigger with HSV values.

Remap

remap(...remaps)

$group

Remaps multiple IDs inside the group to others, e.g. remap([group(1), group(2)], [group(4), group(3)]).

Example

const box = unknown_g();

// Assign a block to the group via obj_props
object({ [obj_props.OBJ_ID]: 1, [obj_props.X]: 150, [obj_props.Y]: 105 })
  .with(obj_props.GROUPS, box)
  .add();

// Move the box 30 units right over 0.5s, then back
box.move(30, 0, 0.5);
box.move(-30, 0, 0.5);

// Toggle it off after 2 seconds
wait(2);
box.toggle_off();

`$color` Methods

A $color value provides methods that emit color channel triggers.

set(c, duration?, blending?)

void

Color trigger — changes the channel to RGB value c (an array [r, g, b]). Use the rgb() helper to build the array.

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

void

Copy Color trigger — copies another color channel to this one. hvs defaults to "0a1a1a0a0".

pulse(color, fade_in?, hold?, fade_out?, exclusive?)

void

Pulse trigger with an RGB color array.

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

void

Pulse trigger with HSV values.

Color Channel Constants

G.js exports named constants for all of GD’s built-in color channels so you never have to remember their numeric IDs:

Constant	Channel
`BG`	Background
`GROUND`	Ground
`LINE`	Line
`_3DLINE`	3D Line
`OBJECT`	Object
`GROUND2`	Ground 2
`BLACK`	Black
`WHITE`	White
`LIGHTER`	Lighter
`MIDDLEGROUND`	Middleground
`MIDDLEGROUND_2`	Middleground 2

Example

// Flash the background red over 0.2s, then back to black
color(BG).set(rgb(255, 0, 0), 0.2);
wait(0.2);
color(BG).set(rgb(0, 0, 0), 0.2);

// Copy the background color to a custom channel
const my_color = unknown_c();
my_color.copy(color(BG), 0.5);

// Pulse with HSV
my_color.pulse_hsv(180, 1, 1, false, false, 0.1, 0.3, 0.1);

`$block` Methods

A $block value provides methods for GD’s collision system.

collision_block(x, y)

GJsObject

Returns a collision block object placed at the given coordinates. Call .add() on the result to add it to the level.

if_colliding(b2, true_id?, false_id?)

void

Collision trigger — calls true_id group when this block collides with b2, and false_id when it stops colliding.

Example

const player_block = unknown_b();
const hazard_block = unknown_b();

// Place the collision blocks in the level
player_block.collision_block(100, 105).add();
hazard_block.collision_block(400, 105).add();

// Define what happens on collision
const die_fn = trigger_function(() => {
  // ... trigger death sequence
});

player_block.if_colliding(hazard_block, die_fn);

Type Annotations

$group, $color, and $block are also exported as TypeScript types for use in type annotations:

import type { $group, $color, $block } from '@g-js-api/g.js/safe';

function shake(target: $group, amount: number): void {
  target.move(amount, 0, 0.1);
  target.move(-amount, 0, 0.1);
}

Objects & Triggers

How to create and configure GD objects using object(), trigger(), and obj_props.

Trigger Functions

Group triggers into callable units with trigger_function() and manage contexts.

Get Started

Core Concepts

Guides

Groups, Colors, and Blocks in G.js

The Three ID Types

Creating IDs

Known IDs — `group()`, `color()`, `block()`

Next-Free IDs — `unknown_g()`, `unknown_c()`, `unknown_b()`

The `specific` Parameter

`$group` Methods

Movement

Rotation and Scale

Visibility and Alpha

Control Flow

Animation

Pulse

Remap

Example

`$color` Methods

Color Channel Constants

Example

`$block` Methods

Example

Type Annotations

Objects & Triggers

Trigger Functions

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Documentation Index

​The Three ID Types

​Creating IDs

​Known IDs — group(), color(), block()

​Next-Free IDs — unknown_g(), unknown_c(), unknown_b()

​The specific Parameter

​$group Methods

​Movement

​Rotation and Scale

​Visibility and Alpha

​Control Flow

​Animation

​Pulse

​Remap

​Example

​$color Methods

​Color Channel Constants

​Example

​$block Methods

​Example

​Type Annotations

Objects & Triggers

Trigger Functions

Build docs developers (and LLMs) love

The Three ID Types

Creating IDs

Known IDs — `group()`, `color()`, `block()`

Next-Free IDs — `unknown_g()`, `unknown_c()`, `unknown_b()`

The `specific` Parameter

`$group` Methods

Movement

Rotation and Scale

Visibility and Alpha

Control Flow

Animation

Pulse

Remap

Example

`$color` Methods

Color Channel Constants

Example

`$block` Methods

Example

Type Annotations