Reading and Modifying Existing GD Levels with G.js

G.js includes a level-reading API that lets your scripts open existing Geometry Dash levels, inspect or modify their objects, and write the result back to disk. This is useful for procedural modifications, automated edits, object filtering, and building tools that work on top of levels you’ve already designed in the GD editor.

The reader APIs interact directly with Geometry Dash’s save files on disk. Always back up your GD save file before running scripts that call .save(). Corrupted save data can result in permanent level loss.

`LevelReader`

LevelReader opens a level by name from a GD save file (the standard CCLocalLevels.dat or a custom path).

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

const reader = new LevelReader(level_name, filename?, reencrypt?);

Parameter	Type	Default	Description
`level_name`	`string`	—	Name of the level to load from the save file
`filename`	`string`	(default GD path)	Path to the GD save file to read from
`reencrypt`	`boolean`	`true`	Whether to re-encrypt the file when saving

Properties and Methods

Member	Type	Description
`.data`	`any`	Parsed level data (object representation of the level)
`.set(lvlstr)`	`function`	Replace the level’s object data with a new level string
`.save()`	`Promise<void>`	Write the modified level back to the save file

Example — Filter and Re-save a Level

import { LevelReader, levelstring_to_obj } from '@g-js-api/g.js/safe';

// Open "My Level" from the default GD save file
const reader = new LevelReader('My Level');

// Inspect the raw level data
console.log(reader.data);

// Decode the level string, filter out all objects with ID 1 (solid block)
// then write the filtered string back
const objects = levelstring_to_obj(reader.data.k4); // k4 is the level string key
const filtered = objects.filter(obj => obj['1'] !== '1');

// Reconstruct a level string from the filtered objects and set it
const newLevelString = filtered.map(obj =>
  Object.entries(obj).map(([k, v]) => `${k},${v}`).join(',')
).join(';');

reader.set(newLevelString);
await reader.save();

console.log('Level saved with solid blocks removed.');

`SingleLevelReader`

SingleLevelReader reads a standalone .gmd level file rather than GD’s main save file. The .gmd format is produced by GD’s “Export Level” feature and is useful for sharing individual levels as files.

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

const reader = new SingleLevelReader(filename);

Parameter	Type	Description
`filename`	`string`	Path to the `.gmd` file to open

Properties and Methods

Member	Type	Description
`.data`	`any`	Parsed level data
`.root`	`any`	Raw root-level data from the file
`.set(lvlstr)`	`function`	Replace the level string
`.add(lvlstr)`	`function`	Append objects from a level string to the existing level
`.save(f?)`	`function`	Save back to disk; optionally provide an alternate output path

Example — Append Objects to a `.gmd` File

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

const reader = new SingleLevelReader('./my-level.gmd');

console.log('Current level data:', reader.data);

// Add extra objects by appending a hand-crafted level string
reader.add('1,1,2,75,3,75;1,1,2,105,3,75;');

// Overwrite the original file with the updated content
reader.save();

`encode_level()` and `decode_level()`

G.js exposes low-level helpers for converting between raw GD level strings and their decoded form.

import { encode_level, decode_level } from '@g-js-api/g.js/safe';

Function	Signature	Description
`encode_level`	`encode_level(level_string)`	Encodes a plain level string into GD’s save format
`decode_level`	`decode_level(data)`	Decodes an encoded GD level string back to plaintext

These are lower-level utilities, typically used when you need to handle the raw bytes that GD writes to disk (e.g., when building your own reader tooling).

import { encode_level, decode_level } from '@g-js-api/g.js/safe';

const raw = '1,1,2,45,3,45;';
const encoded = encode_level(raw);
console.log('Encoded:', encoded);

const decoded = decode_level(encoded);
console.log('Decoded:', decoded); // → '1,1,2,45,3,45;'

The `level` Object

During level generation, G.js exposes a level helper object that provides access to already-added objects and the current level string. This is useful for reading back information about the level you are actively building.

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

Member	Type	Description
`level.objects`	`any[]`	Array of all objects added to the level so far
`level.raw_levelstring`	`string`	The raw level string representation of current objects
`level.get_objects(prop, pattern)`	`function`	Filter objects by a property key and a pattern function

`level.get_objects(prop, pattern)`

level.get_objects(prop: string | number, pattern: (val: any) => boolean): any[]

Returns all objects where the given property matches the predicate. prop can be a numeric GD property ID or a string key name.

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

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

// Add some objects first...
object({ [obj_props.OBJ_ID]: 1, [obj_props.X]: 45, [obj_props.Y]: 45 }).add();
object({ [obj_props.OBJ_ID]: 1, [obj_props.X]: 75, [obj_props.Y]: 45 }).add();
object({ [obj_props.OBJ_ID]: 2, [obj_props.X]: 105, [obj_props.Y]: 45 }).add();

// Get all objects with OBJ_ID === 1
const solidBlocks = level.get_objects(obj_props.OBJ_ID, val => val === 1);
console.log(`Found ${solidBlocks.length} solid blocks`);

`levelstring()` and `levelstring_to_obj()`

These utilities let you import or parse level strings within your generation scripts.

`levelstring(string)`

Parses a level string and returns a helper object with the parsed objects and an add() method that inserts all of them into the current level.

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

const parsed = levelstring('1,1,2,45,3,45;1,2,2,75,3,75;');
console.log('Objects:', parsed.objects);

// Add all objects from the string into the current level
parsed.add();

`levelstring_to_obj(string)`

A lower-level converter that takes a raw level string and returns an array of Dictionary objects without doing any processing or type conversions. Use this when you need direct access to raw GD property maps.

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

const objects = levelstring_to_obj('1,1,2,45,3,45;1,2,2,75,3,75;');
// objects = [ { '1': '1', '2': '45', '3': '45' }, { '1': '2', '2': '75', '3': '75' } ]
console.log(objects);

Complete Workflow Example

The following shows a realistic workflow: open an existing level, find all spike objects (GD ID 8), move them 30 units upward, and save the result.

import { LevelReader, levelstring_to_obj, encode_level } from '@g-js-api/g.js/safe';

const SPIKE_ID = '8'; // GD object ID for spike

const reader = new LevelReader('Obstacle Course');

// Parse the level string (stored in the 'k4' property of level data)
const rawString = reader.data.k4 ?? '';
const objects = levelstring_to_obj(rawString);

// Move all spikes up by 30 units
const updated = objects.map(obj => {
  if (obj['1'] === SPIKE_ID) {
    const currentY = parseFloat(obj['3'] ?? '0');
    return { ...obj, '3': String(currentY + 30) };
  }
  return obj;
});

// Rebuild the level string
const newLevelString = updated
  .map(obj => Object.entries(obj).map(([k, v]) => `${k},${v}`).join(','))
  .join(';');

reader.set(newLevelString);
await reader.save();

console.log('All spikes raised by 30 units.');

Safe Mode

Import only what you need without polluting global scope.

Export Modes

Learn about savefile, levelstring, live_editor, and gmd export types.

Objects & Triggers

Understand the GJsObject model and how .add() works.

General Purpose API

Reference for levelstring, level, and other general utilities.

Get Started

Core Concepts

Guides

Reading and Modifying Existing GD Levels with G.js

`LevelReader`

Properties and Methods

Example — Filter and Re-save a Level

`SingleLevelReader`

Properties and Methods

Example — Append Objects to a `.gmd` File

`encode_level()` and `decode_level()`

The `level` Object

`level.get_objects(prop, pattern)`

`levelstring()` and `levelstring_to_obj()`

`levelstring(string)`

`levelstring_to_obj(string)`

Complete Workflow Example

Safe Mode

Export Modes

Objects & Triggers

General Purpose API

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Documentation Index

​LevelReader

​Properties and Methods

​Example — Filter and Re-save a Level

​SingleLevelReader

​Properties and Methods

​Example — Append Objects to a .gmd File

​encode_level() and decode_level()

​The level Object

​level.get_objects(prop, pattern)

​levelstring() and levelstring_to_obj()

​levelstring(string)

​levelstring_to_obj(string)

​Complete Workflow Example

Safe Mode

Export Modes

Objects & Triggers

General Purpose API

Build docs developers (and LLMs) love

`LevelReader`

Properties and Methods

Example — Filter and Re-save a Level

`SingleLevelReader`

Properties and Methods

Example — Append Objects to a `.gmd` File

`encode_level()` and `decode_level()`

The `level` Object

`level.get_objects(prop, pattern)`

`levelstring()` and `levelstring_to_obj()`

`levelstring(string)`

`levelstring_to_obj(string)`

Complete Workflow Example