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 G.js script must tell the library where its output should go before any level content is created. This is done with a single call to $.exportConfig(), which accepts an ExportConfig object describing the export type and any additional options. Getting this call right — and getting it in before any GD objects, triggers, or groups are created — is the first step in every G.js project.

​
$.exportConfig(conf) — The Required Setup Call

declare function exportConfig(conf: ExportConfig): Promise<any>;
$.exportConfig returns a Promise and must be await-ed. Place it at the very top of your script, immediately after your import statement and before any GD-related code. 
import '@g-js-api/g.js';

// ✅ Correct — awaited before any GD content
await $.exportConfig({
  type: 'savefile',
  options: { info: true },
});

// GD code starts here...
const my_group = unknown_g();
If you call $.exportConfig after creating GD objects or groups, those items may be silently dropped or the export may behave incorrectly. Always await the config call first.

​
The ExportConfig Interface

interface ExportConfig {
  type: 'levelstring' | 'savefile' | 'live_editor' | 'gmd';
  options?: ExportOptions;
}
type selects the export destination. options is an optional bag of configuration flags described in the next section.

​
Export Types

​
'savefile' — Write Directly to the GD Save File

Saves the generated level directly into Geometry Dash’s local save file. This is the most common mode for desktop development. 
await $.exportConfig({
  type: 'savefile',
  options: {
    level_name: 'My Level',
    info: true,
  },
});
G.js locates the save file automatically. Use the path option to override the save file location if needed.

​
'live_editor' — Stream to the WSLiveEditor Mod

Streams the level in real time to the WSLiveEditor Geometry Dash mod. This lets you preview changes without restarting the game. 
await $.exportConfig({
  type: 'live_editor',
  options: {
    replacePastObjects: true,
  },
});

​
'levelstring' — Return the Raw Level String

Exports the level as a raw GD level string and returns it from the exportConfig call. Store the result in a variable — it is not written anywhere automatically. 
const levelstring_result = await $.exportConfig({
  type: 'levelstring',
  options: { optimize: true },
});

// levelstring_result now holds the raw GD level string
console.log(levelstring_result);
Use 'levelstring' mode when you want to post-process the output, pipe it to another tool, or integrate G.js into a larger build pipeline.

​
'gmd' — Export to a .gmd File

Writes the level to a .gmd file on disk. Geometry Dash can import .gmd files directly. 
await $.exportConfig({
  type: 'gmd',
  options: {
    gmdOutput: './my-level.gmd',
    level_name: 'My Level',
  },
});

​
The ExportOptions Interface

All options are optional. Combine them as needed for your workflow. 
interface ExportOptions {
  info?: boolean;
  group_count_warning?: boolean;
  level_name?: string;
  path?: string;
  reencrypt?: boolean;
  optimize?: boolean;
  replacePastObjects?: boolean;
  removeGroup?: number | { value: number };
  triggerPositioningAllowed?: boolean;
  trigger_pos_start?: number;
  gmdOutput?: string;
}
​
info
boolean
When true, prints a summary of level statistics (object count, group count, etc.) to the console when the script finishes. Great for debugging.
​
group_count_warning
boolean
When true, G.js emits a warning if the level’s group count approaches the GD limit of 9999.
​
level_name
string
The name of the level to create or overwrite in the save file. Defaults to a generic name if not set.
​
path
string
Override the path to the GD save file. Useful on non-standard installations or when using 'savefile' mode on a custom path.
​
reencrypt
boolean
When true, G.js re-encrypts the save file after writing, matching GD’s own save format.
​
optimize
boolean
When true, runs G.js’s built-in optimizer over the level before exporting. The optimizer merges redundant triggers and reduces group usage.
​
replacePastObjects
boolean
When true, removes objects previously added by G.js before writing the new ones. Use this with 'live_editor' mode to avoid accumulating objects across re-runs.
​
removeGroup
number | { value: number }
Removes all objects belonging to the specified group before writing. Accepts either a raw group number or a $group value (which carries a .value property).
​
triggerPositioningAllowed
boolean
When true, G.js is allowed to reposition triggers along the X axis for cleaner visual layout inside the editor. Requires trigger_pos_start to define the starting X offset.
​
trigger_pos_start
number
The X coordinate at which G.js begins placing triggers when triggerPositioningAllowed is true.
​
gmdOutput
string
Path to the output .gmd file. Only used with type: 'gmd'.

​
Complete Examples

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

await $.exportConfig({
  type: 'savefile',
  options: {
    level_name: 'Platformer Demo',
    info: true,
    optimize: true,
    replacePastObjects: true,
  },
});

// ... level code

​
Using the Safe Import

If you prefer not to pollute the global scope, import from @g-js-api/g.js/safe and call exportConfig directly: 
import { $, exportConfig, unknown_g, trigger_function, obj_props } from '@g-js-api/g.js/safe';

await exportConfig({
  type: 'savefile',
  options: { level_name: 'Safe Mode Level', info: true },
});

// ... level code using named imports

​
levelstring(string) — Parsing Existing Level Strings

G.js also exports a levelstring() helper (not to be confused with the export type) that parses an existing GD level string and returns an object with an .add() method. This lets you incorporate objects from existing levels into your script. 
declare const levelstring: (string: string) => { objects: any[]; add: () => void };

import { levelstring } from '@g-js-api/g.js/safe';

// Parse an existing level string and add all its objects to the current level
const imported = levelstring('H4sIAAAAAAAAA...');
imported.add();
Type conversions are not done automatically when parsing with levelstring(). Property values will be raw strings as they appear in the GD level format.

Objects & Triggers

Create and configure GD objects and triggers in your level script.

Trigger Functions

Understand contexts and callable trigger groups.

Groups, Colors & Blocks

Work with GD group, color, and block IDs.

Quick Start

Get a full level running in minutes.

Build docs developers (and LLMs) love

Get started for freeTalk to us