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.

The $ object is the central configuration and utility namespace in G.js. It bundles the most commonly used top-level helpers — exporting the level, adding objects, printing debug info, and wiring up trigger functions — into a single import-friendly reference. In global mode (the default), $ is injected automatically into the global scope so you can call $.exportConfig(...) without any import. In safe mode you import it explicitly from the package. 
// global mode — $ is already in scope
await $.exportConfig({ type: 'levelstring' });

// safe mode
import $, { exportConfig } from '@g-js-api/g.js/safe';
await $.exportConfig({ type: 'levelstring' });
// or use the named export directly
await exportConfig({ type: 'levelstring' });
exportConfig is available both as $.exportConfig and as a standalone named export from @g-js-api/g.js/safe. In safe mode either form works identically.

​
Members

​
$.exportConfig(conf)

Configures how the finished level is exported and kicks off the export pipeline. This must be called before any GD content is added to the level. It returns a Promise, so always await it at the top level of your script. 
await $.exportConfig({
  type: 'savefile',
  options: {
    level_name: 'My Level',
    info: true,
    optimize: true,
  },
});
​
conf
ExportConfig
required
The export configuration object. See ExportConfig below.

​
$.add(...objects)

Adds one or more GD objects to the current level context. Equivalent to calling .add() on each object individually. 
const spike = object({ [obj_props.OBJ_ID]: 8, [obj_props.X]: 300, [obj_props.Y]: 105 });
$.add(spike);
​
objects
GJsObject[]
required
One or more objects created with object() or trigger().

​
$.print(...args)

Prints debug information to the console during level compilation. Accepts any number of arguments, just like console.log. 
$.print('Group allocated:', my_group);
​
args
any[]
required
Values to print. All arguments are forwarded as-is.

​
$.callback_objects(cb)

Registers a callback function that is called on every object in the level right before export. Use this to post-process or audit objects globally. 
$.callback_objects((obj) => {
  // force all objects onto Z layer 1
  obj[obj_props.Z_LAYER] = 1;
});
​
cb
Function
required
Callback invoked with each raw object dictionary before the level is exported.

​
$.extend_trigger_func(t, cb)

Extends an existing trigger function group t by appending the triggers produced inside cb to it. This lets you add more behavior to a trigger function after it has already been created. 
const my_fn = trigger_function(() => {
  my_group.move(10, 0, 0.5);
});

$.extend_trigger_func(my_fn, () => {
  my_group.alpha(0, 0.3);
});
​
t
TriggerFunctionGroup
required
The trigger function group to extend.
​
cb
(group: any) => void
required
Callback whose triggers are appended to the existing function group. Receives the group as its first argument, mirroring the trigger_function API.

​
$.trigger_fn_context()

Returns the current context group when called from inside a trigger_function callback. Useful when you need a reference to the group that owns the current trigger function, for example to remap IDs or stop execution. 
const fn = trigger_function((group) => {
  const ctx = $.trigger_fn_context();
  ctx.call(0.5); // schedule a self-call
});
Returns any — the $group that represents the current trigger function context.

​
ExportConfig

​
type
'levelstring' | 'savefile' | 'live_editor' | 'gmd'
required
The export target.
ValueBehaviour
levelstringPrints the raw GD levelstring to stdout
savefileWrites the level directly to the GD save file
live_editorSends the level to the GD Live Editor
gmdExports the level as a .gmd file
​
options
ExportOptions
Optional fine-grained export settings. See ExportOptions below.

​
ExportOptions

​
info
boolean
default:"false"
When true, prints a summary of object counts, group usage, and other stats to the console after export.
​
group_count_warning
boolean
default:"true"
When true, emits a warning if the level is close to or exceeds the 9 999-group limit.
​
level_name
string
The name to give the exported level. Used when writing to the save file or exporting as .gmd.
​
path
string
File path for the output when using the savefile or gmd export types. Defaults to the GD save location.
​
reencrypt
boolean
default:"true"
Whether to re-encrypt the save file after writing. Disable only if you are post-processing the file yourself.
​
optimize
boolean
default:"false"
When true, runs the G.js optimizer over the level before export, deduplicating trigger functions and collapsing redundant groups.
​
replacePastObjects
boolean
default:"false"
When true, replaces existing level objects in the save file rather than appending to them.
​
removeGroup
number | { value: number }
A group ID (or boxed group ID object) whose objects should be stripped from the output before export. Handy for removing editor-only helper objects.
​
triggerPositioningAllowed
boolean
default:"true"
When true, G.js automatically repositions trigger objects into a neat column off-screen so they do not collide with gameplay objects.
​
trigger_pos_start
number
default:"-100"
The X coordinate at which to start placing auto-positioned triggers. Negative values place them off the left edge of the level.
​
gmdOutput
string
Override the output path specifically for gmd exports. Takes precedence over path when both are set.

​
Full example

// safe mode example with all common options
import $, { exportConfig, group, obj_props, object } from '@g-js-api/g.js/safe';

await exportConfig({
  type: 'savefile',
  options: {
    level_name: 'Platformer Demo',
    info: true,
    optimize: true,
    group_count_warning: true,
    replacePastObjects: true,
    triggerPositioningAllowed: true,
    trigger_pos_start: -200,
  },
});

// ... add objects, triggers, groups, etc.

object({
  [obj_props.OBJ_ID]: 1,
  [obj_props.X]: 75,
  [obj_props.Y]: 105,
}).add();
Always await the exportConfig call. Forgetting the await is the most common source of empty-level exports.

Build docs developers (and LLMs) love

Get started for freeTalk to us