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.

Every visual element and gameplay mechanic in a Geometry Dash level is either an object or a trigger. G.js models both as GJsObject values — plain JavaScript objects with a fluent builder API that lets you set properties, chain modifications, and finally commit the result to your level with a single .add() call.

​
The GJsObject Interface

All objects and triggers created by G.js share the same GJsObject interface: 
interface GJsObject {
  type: 'object';
  obj_props: Dictionary;
  with(prop: string | number, value: any): GJsObject;
  add(): void;
}
MemberDescription
typeAlways 'object'. Useful for distinguishing GJsObjects from other G.js values at runtime.
obj_propsA dictionary mapping property keys to their current values. You can inspect this at any time.
.with(prop, value)Returns a new GJsObject with the given property set. This method is chainable.
.add()Commits the object to the level currently being built. Must be called for the object to appear.
.with() does not mutate the original object — it returns a new GJsObject with the additional property applied, so you can safely reuse a base object.

​
Creating Objects with object(dict)

The object() function takes a dictionary of obj_props keys mapped to values and returns a GJsObject. Use it for any non-trigger GD object such as blocks, spikes, decorations, and text. 
import '@g-js-api/g.js';

// A solid block at grid position (75, 105)
object({
  [obj_props.OBJ_ID]: 1,
  [obj_props.X]: 75,
  [obj_props.Y]: 105,
}).add();
You can also chain .with() calls after object() to layer on extra properties before calling .add(): 
object({
  [obj_props.OBJ_ID]: 1,
  [obj_props.X]: 75,
  [obj_props.Y]: 105,
})
  .with(obj_props.ROTATION, 45)
  .with(obj_props.GROUPS, my_group)
  .add();

​
Creating Triggers with trigger(dict)

The trigger() function has the same signature as object() but is specifically intended for trigger objects. Under the hood, G.js uses this distinction to handle trigger positioning when triggerPositioningAllowed is enabled in your export config. 
// A manually-constructed move trigger
trigger({
  [obj_props.OBJ_ID]: 901,
  [obj_props.TARGET]: group(1),
  [obj_props.MOVE_X]: 150,
  [obj_props.DURATION]: 0.5,
}).add();
For most built-in GD triggers you will call methods on $group, $color, or $block instead of building triggers manually. Reserve trigger() for low-level use cases or trigger types not yet wrapped by G.js.

​
Converting Strings to Text Objects with .to_obj()

JavaScript strings get a .to_obj() extension method that converts the string into a GD text object and returns a GJsObject. You can then chain .with() to position and group it before calling .add(). 
let label_group = unknown_g();

'Hello, World!'
  .to_obj()
  .with(obj_props.X, 45)
  .with(obj_props.Y, 45)
  .with(obj_props.GROUPS, label_group)
  .add();

​
The obj_props Dictionary

obj_props is an exported dictionary that maps human-readable property names to their internal GD integer keys. Always use obj_props keys rather than raw numbers so your code stays readable and forward-compatible. Here are the most commonly used keys:
KeyDescription
obj_props.OBJ_IDThe object’s GD type ID
obj_props.XHorizontal position
obj_props.YVertical position
obj_props.GROUPSGroup assignment (single group or array)
obj_props.ROTATIONRotation in degrees
obj_props.COLORPrimary color channel
obj_props.COLOR_2Secondary color channel
obj_props.TARGETTarget group (used by many triggers)
obj_props.DURATIONTrigger duration
obj_props.MOVE_XX movement amount (move trigger)
obj_props.MOVE_YY movement amount (move trigger)
obj_props.EASINGEasing type
obj_props.TEXTText content (text objects)
The full list of obj_props keys is documented in the Object Properties reference.

​
The obj_ids Export

obj_ids is a companion export that maps friendly names to GD object type IDs. Use it as the value for obj_props.OBJ_ID instead of hard-coding integers. 
import { obj_ids, obj_props, object } from '@g-js-api/g.js/safe';

object({
  [obj_props.OBJ_ID]: obj_ids.SPIKE,
  [obj_props.X]: 300,
  [obj_props.Y]: 105,
}).add();

​
Chaining .with() for Clean Configuration

Because .with() returns a new GJsObject, you can build a base template and derive specialised versions from it: 
const base_block = object({
  [obj_props.OBJ_ID]: 1,
  [obj_props.Y]: 105,
});

// Two blocks at different X positions, sharing all other properties
base_block.with(obj_props.X, 75).add();
base_block.with(obj_props.X, 150).add();

​
Adding Objects to the Level

.add() is the final step — nothing appears in your level until it is called. Forgetting .add() is the most common source of “missing objects” bugs. 
// ❌ Object is created but never added
const my_block = object({ [obj_props.OBJ_ID]: 1, [obj_props.X]: 75, [obj_props.Y]: 105 });

// ✅ Object is added to the level
object({ [obj_props.OBJ_ID]: 1, [obj_props.X]: 75, [obj_props.Y]: 105 }).add();
You can also call $.add(...objects) to add multiple pre-built GJsObject values at once.

​
Full Example

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

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

// A spike at (300, 105) assigned to group 5, rotated 180°
const spike_group = group(5);

object({
  [obj_props.OBJ_ID]: obj_ids.SPIKE,
  [obj_props.X]: 300,
  [obj_props.Y]: 105,
})
  .with(obj_props.ROTATION, 180)
  .with(obj_props.GROUPS, spike_group)
  .add();

// A text label above it
'Danger!'
  .to_obj()
  .with(obj_props.X, 300)
  .with(obj_props.Y, 165)
  .add();

Groups, Colors & Blocks

Learn how to create and use $group, $color, and $block IDs with their built-in trigger methods.

Object Properties Reference

Full listing of every key available in the obj_props dictionary.

Build docs developers (and LLMs) love

Get started for freeTalk to us