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 distributed as an npm package and runs on Node.js. This page walks you through installing the package, choosing an import style, and making sure TypeScript is configured correctly before you write your first line of level code.

​
Prerequisites

  • Node.js — any reasonably modern LTS release (16+) works. G.js uses ES modules ("type": "module" is recommended for your project).
  • A supported platform — Windows, macOS, Linux, or Android.
  • A package manager: npm, yarn, or pnpm.

​
Install the Package

npm install @g-js-api/g.js
The package is published as @g-js-api/g.js on the npm registry. No build step or bundler is required — you import it directly in your Node.js script.

​
Project Setup

1
Create your project file
2
Create a new JavaScript (or TypeScript) file for your level script. Using the .mjs extension or setting "type": "module" in your package.json is recommended because G.js is an ES module.
3
{
  "type": "module"
}
4
Choose an import style
5
G.js supports two import styles. Pick one and stick with it for your project.
6
Option 1 — Global import (convenient, recommended for quick scripts)
7
import '@g-js-api/g.js';
8
This single import registers all G.js functions and constants as global variables. After this line, trigger_function, unknown_g, group, counter, obj_props, wait, and every other exported name are available anywhere in your file without further destructuring.
9
Option 2 — Safe mode (explicit, recommended for larger projects)
10
import {
  group,
  color,
  trigger_function,
  counter,
  unknown_g,
  unknown_c,
  unknown_b,
  obj_props,
  wait,
  ignore_context_change,
  on, touch,
  $
} from '@g-js-api/g.js/safe';
11
The /safe entry point exports everything individually and adds nothing to the global scope. Import exactly the names your file uses. See Safe Mode for a deeper guide.
12
Call $.exportConfig() before any level content
13
$.exportConfig() is an async function that tells G.js how to export the finished level. It must be awaited, and it must run before you create any groups, objects, or triggers.
14
await $.exportConfig({
  type: 'savefile',       // or 'levelstring', 'live_editor', 'gmd'
  options: {
    info: true,           // print level stats when the script finishes
    level_name: 'My Level'
  }
});
15
Placing $.exportConfig() after any GD content (objects, groups, trigger calls) will produce incorrect or empty output. Always put it at the very top of your level logic, immediately after your imports.
16
Write your level code
17
With the config in place you can start using the full G.js API. Here is the minimal skeleton:
18
import '@g-js-api/g.js';

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

// your level code goes here
let myGroup = unknown_g();

'Hello, World!'
  .to_obj()
  .with(obj_props.X, 45)
  .with(obj_props.Y, 45)
  .with(obj_props.GROUPS, myGroup)
  .add();
19
Run the script
20
node level.js
21
G.js will build the level and export it according to the type you specified in exportConfig. With type: 'savefile' it writes directly to your GD save. With type: 'levelstring' it prints the raw string to stdout.

​
TypeScript Support

The package ships its own type declarations. The "types" field in package.json points to index.d.ts, which re-exports all types from the safe module. No @types/ package is needed. For the global import style, the ambient declarations in src/runtime.d.ts describe the globals that are injected when you import '@g-js-api/g.js'. If your editor does not pick these up automatically, add a triple-slash reference or include the file in your tsconfig.json:
tsconfig.json
{
  "compilerOptions": {
    "module": "NodeNext",
    "moduleResolution": "NodeNext"
  }
}
For the safe mode style, all types are inferred directly from the named exports — no extra configuration required. Key types exported from @g-js-api/g.js:
TypeDescription
ExportConfigArgument shape for $.exportConfig()
ExportOptionsOptions object within ExportConfig
GJsObjectThe object returned by object() and .to_obj()
TriggerFunctionGroupReturn value of trigger_function(), with .call() and .remap()
CounterFull counter interface including arithmetic and comparison methods
FloatCounterCounter with additional round() and floor() methods
ContextLow-level context class for advanced trigger-context manipulation

​
Export Modes at a Glance

typeWhat happens
levelstringReturns the raw GD levelstring; store it in a variable or print it
savefileWrites the level directly into your local GD save file
live_editorStreams objects to GD via the WSLiveEditor mod (live preview)
gmdExports a .gmd file compatible with GD World / external editors
See Export Modes for the full breakdown of options for each type.

Build docs developers (and LLMs) love

Get started for freeTalk to us