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.

Collision blocks are invisible hitbox identifiers that let Geometry Dash levels detect when two things occupy the same space. By assigning a block ID to objects and then querying whether those IDs are colliding, you can build platform detectors, hit detection, proximity sensors, and other gameplay logic entirely through G.js — no manual trigger wiring required. The $block class wraps a numeric block ID and provides helper methods for placing collision block objects and for creating conditional logic based on collision state. For a higher-level look at how blocks interact with events see /guides/events.

​
Creating Blocks

​
block(id)

Creates a $block instance from a known block ID. G.js marks this ID as in-use so it will not be returned by unknown_b(). 
const player_block = block(1); // assumes player already has block ID 1
​
id
number
required
The GD collision block ID.
Returns $block

​
unknown_b()

Allocates and returns the next free block ID. Use this whenever you need a collision block but do not need a specific ID. 
const platform_block = unknown_b();
Returns $block

​
new $block(a, specific?)

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

function makeDetector(b: $block) {
  return b.collision_block(0, 0);
}

​
Methods

​
collision_block(x, y)

Returns a collision block object placed at the given coordinates. Call .add() on the result to insert it into the level.
​
x
number
required
X coordinate where the collision block object will be placed.
​
y
number
required
Y coordinate where the collision block object will be placed.
Returns GJsObject 
const sensor = unknown_b();
sensor.collision_block(300, 105).add();

​
if_colliding(b2, true_id?, false_id?)

Creates a Collision trigger that continuously evaluates whether this block and b2 are overlapping. When they are, true_id is called; when they are not, false_id is called.
​
b2
$block
required
The other block to test collision against.
​
true_id
$group
Group to call when the two blocks are colliding. If omitted, nothing happens on collision.
​
false_id
$group
Group to call when the two blocks are not colliding. If omitted, nothing happens when not colliding.
platform_block.if_colliding(player_block, on_ground, in_air);

​
Collision Events

For event-driven (one-shot) collision detection, use the collision and collision_exit functions from the events module rather than if_colliding. These fire a callback group exactly once when a collision begins or ends. 
import { on, collision, collision_exit } from '@g-js-api/g.js/safe';

const floor = unknown_b();
const player = block(1);

// Fires once when player lands on the floor
on(collision(floor, player), () => {
  landing_effect_group.call();
});

// Fires once when player leaves the floor
on(collision_exit(floor, player), () => {
  jump_dust_group.call();
});
​
a
$block
required
First collision block.
​
b
$block
required
Second collision block.
​
P1
boolean
When true, restricts the event to Player 1’s collision block only.
​
P2
boolean
When true, restricts the event to Player 2’s collision block only.
P1 and P2 flags are relevant in two-player levels where both players share the same block ID. Passing P1: true makes the collision event fire only when Player 1 is involved, preventing false positives from Player 2.

​
Code examples

const platform_block = unknown_b();
const player_block   = block(1); // player collision block ID

const on_ground = unknown_g();
const in_air    = unknown_g();

// Place the collision hitbox on the platform object
platform_block.collision_block(300, 105).add();

// Continuously test and branch
platform_block.if_colliding(player_block, on_ground, in_air);

// Define what happens when grounded vs airborne
trigger_function(() => {
  // grounded — enable coyote-time timer, etc.
  coyote_counter.set(1);
}, on_ground);

trigger_function(() => {
  // airborne — clear grounded state
  coyote_counter.set(0);
}, in_air);
Prefer if_colliding for continuous state checks (is the player on the ground right now?) and prefer collision / collision_exit events from /guides/events for one-shot reactions (do something the moment the player lands).
Collision block IDs must be unique per logical sensor. Reusing the same block ID on multiple unrelated objects will cause their collision triggers to fire together, leading to unexpected behaviour. Always use unknown_b() when you need a fresh ID.

Build docs developers (and LLMs) love

Get started for freeTalk to us