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 is a JavaScript library that lets you build Geometry Dash levels entirely in code. Instead of dragging and connecting triggers in the GD editor by hand, you describe your level’s logic — move triggers, color changes, spawn sequences, counters, camera effects, and more — as ordinary JavaScript, then export the result directly into the game. If you have ever found yourself spending hours wiring up spawn triggers for a looping effect or manually tracking which group IDs are still free, G.js handles all of that for you automatically.

​
Why G.js?

Manually placing triggers in the GD editor is tedious at scale. A moving platform that reacts to the player, loops back to its origin, and flashes the background involves at least a dozen triggers, careful group management, and precise spawn-delay arithmetic. G.js replaces that workflow with readable JavaScript:
  • Automatic ID management — unknown_g(), unknown_c(), and unknown_b() allocate the next free group, color, and block IDs so you never collide with existing ones.
  • Declarative objects — build any GD object or trigger from a property dictionary and call .add() to place it.
  • Trigger functions as code — wrap trigger sequences in trigger_function(() => { ... }) and call them like ordinary functions.
  • Context tracking — G.js tracks the active spawn-delay context for you, so loops, delays, and conditional branches just work.
  • Multiple export targets — export to a raw levelstring, write straight to your GD savefile, connect to the live editor, or produce a .gmd file.

​
API Style: Global vs. Safe Mode

G.js ships two import styles so you can choose the right level of explicitness for your project. Global import (default) — import '@g-js-api/g.js' registers everything as global variables. Functions like trigger_function, unknown_g, group, counter, obj_props, and wait are available everywhere in your file without any import destructuring. This is the style shown in most examples and is the most convenient for quick scripts. Safe mode — import { group, trigger_function, counter, ... } from '@g-js-api/g.js/safe' gives you explicit, named imports only. Nothing is added to the global scope. This is the better choice for larger codebases, monorepos, or any project where polluting globals would cause conflicts. Both styles expose the same functionality; the only difference is how names enter scope.

​
Core Concepts

ConceptWhat it is
GroupsInteger IDs attached to objects. group(id) wraps a known ID; unknown_g() reserves the next free one. Groups are the target of move, toggle, alpha, and spawn triggers.
ColorsInteger color-channel IDs. color(id) and unknown_c() work the same way as groups.
BlocksCollision block IDs used by collision triggers. unknown_b() reserves one.
ObjectsAny GD object built with object({ ... }) or 'text'.to_obj(), configured with .with(prop, value), and placed with .add().
Trigger functionsA group of triggers wrapped with trigger_function(() => { ... }). Returns a TriggerFunctionGroup you can .call() to spawn it.
CountersIn-game item counters created with counter(). Support arithmetic, comparisons, display, and looping via while_loop.
Eventson(touch()), on(death()), on(collision(...)), and more — bind GD game events to trigger functions.

​
GD 2.2 Support

G.js has broad coverage of features introduced in Geometry Dash 2.2. The following are all supported:
  • Item triggers — item_edit, item_comp, compare; full counter and float-counter arithmetic
  • Camera triggers — camera_offset, camera_static, camera_zoom, camera_mode, camera_rotate, camera_edge
  • ID remapping — remappable() lets you write parameterized trigger systems that operate on runtime-supplied group IDs
  • Keyframes — keyframe_system for object animation sequences
  • Random and sequence triggers — random(), advanced_random(), sequence()
  • Song triggers — song() for full audio control including volume, speed, looping, and spatial audio
  • Particle systems — particle_system({ ... }) with a dedicated property map (particle_props)
  • Shader triggers — sepia, hue_shift, grayscale, pixelate, chromatic, glitch, bulge, split_screen, and shader_layers
G.js is still actively evolving. The sfx trigger and full shader trigger coverage are the two remaining notable gaps. Check the GitHub repository for the latest status before relying on those features.

​
Supported Platforms

G.js runs on Node.js and supports exporting to GD on the following platforms:
  • Windows
  • macOS
  • Linux
  • Android

​
Community and Source

GitHub

Browse the source code, open issues, and follow development on GitHub.

Discord

Get usage help, share levels, and discuss G.js with the community on Discord.

​
Next Steps

Installation

Install the npm package and configure your Node.js project.

Quickstart

Build a moving text loop in under 30 lines of JavaScript.

Build docs developers (and LLMs) love

Get started for freeTalk to us