Skip to content

user_cli_docs

Jump to bottom
Francisco Dias edited this page Apr 9, 2026 · 7 revisions

extgen - User Manual

extgen is a schema-driven code generator for GameMaker native extensions. It generates language bindings, platform glue code, and CMake build systems for all supported GameMaker targets from a single IDL input.

Table of Contents

  1. Overview
  2. Installation & Invocation
  3. Project Initialization
  4. Configuration File Overview
  5. Profiles
  6. GameMaker Generation
  7. Targets (Platforms)
  8. Build System Configuration
  9. Extras (Documentation)
  10. Path Resolution Rules
  11. Common Workflows
  12. Minimal Example

1. Overview

extgen takes a GMIDL schema (.gmidl, .json, etc.) and produces:

  • C++ native bindings
  • GML bindings
  • Platform glue code (Android, iOS, consoles, etc.)
  • A complete CMake project
  • Optional documentation

Everything is controlled through a JSON configuration file validated by a generated JSON Schema.

If the schema validates, extgen will run.

2. Installation & Invocation

Basic usage

extgen --config path/to/config.json

Initialize a new project

extgen --init path/to/folder

This creates:

  • config.json
  • extgen.schema.json

The config file automatically references the schema for editor validation and auto-completion.

3. Project Initialization (--init)

When you run:

extgen --init ./my-extension

extgen generates a JSON Schema describing all supported options, creates a minimal config.json, and sets the $schema property automatically.

The config file can be opened immediately in any schema-aware editor (VS Code recommended).

4. Configuration File Overview

A simplified configuration file:

{
  "$schema": "./extgen.schema.json",
  "input": "./api.gmidl",
  "root": "./",
  "profile": "Full",
  "gamemaker": { ... },
  "targets": { ... },
  "build": { ... },
  "extras": { ... }
}

Top-level fields

Field Description
$schema Path to the JSON schema (auto-managed)
input Path to the GMIDL input file
root Root output directory
profile Controls what extgen emits
gamemaker GameMaker artifacts configuration
targets Platform targets
build CMake & build settings
extras Optional generators (docs, etc.)

5. Profiles

The profile field controls what categories of output are generated.

"profile": "Full"
Profile Meaning
Full Emit bindings + native code + build system
BindingsOnly Emit GML / language bindings only
BuildOnly Emit only CMake & build files

6. GameMaker Generation (gamemaker)

Controls all GameMaker-related outputs. Split into four independent generators:

  • wrappers - generated GML API wrappers (what your game calls)
  • runtime - runtime support (GMExtensionCore support code)
  • yy - .yy generation or patching (function declarations + extension metadata)
  • injectors - optional integration helpers

Example:

"gamemaker": {
  "wrappers": {
    "enabled": true,
    "outputFile": "extension.gml"
  },
  "runtime": {
    "enabled": true,
    "outputFile": "ext_runtime.gml"
  },
  "yy": {
    "enabled": true,
    "outputFile": "./declarations.yy",
    "mode": "patch",
    "extensionName": "MyExtension",
    "extensionFileName": "MyExtension.yy",
    "patchFrameworks": true
  },
  "injectors": {
    "enabled": false,
    "outputFolder": "./injectors"
  }
}

wrappers

Generated GML wrapper API - the functions your GML code calls.

Field Description
enabled Enable wrapper generation
outputFile Output .gml file path

Important

extgen does not create GameMaker IDE assets. wrappers.outputFile should point to an existing .gml script asset in your extension, or a path you manage as part of your build/export flow.

runtime

Emits the runtime support code required by generated wrappers (GMExtensionCore support functions).

Field Description
enabled Enable runtime emission
outputFile Output .gml file path

Note

This is the support layer used by the generated bindings (the official GMExtensionCore).

yy

Controls generation or patching of .yy content for function declarations and extension metadata.

Field Description
enabled Enable .yy generation/patching
outputFile Output path for the generated .yy
mode (required) "plain" or "patch"
extensionName Optional extension display name (used by patch mode)
extensionFileName Optional extension .yy filename (used by patch mode)
patchFrameworks When patching, also patch iOS/tvOS frameworks/link settings where applicable

yy.mode

  • plain - produces a standalone .yy snippet which you can append or merge manually.
  • patch - patches the target file directly (recommended for automation).

Important

In patch mode, treat the extension .yy as build-managed output. This keeps function declarations in sync with GMIDL without manual edits.

injectors

Optional output for integration helpers.

Field Description
enabled Enable injector output generation
outputFolder Folder to write injector scripts/files

Important

Enable this if your extension needs to target GMRT.

7. Targets (Platforms)

All native output is target-driven. Each enabled target activates platform-specific emitters and build presets.

Common target fields

Field Description
enabled Enable this platform
outputFolder Where the final binary is copied

Desktop Targets

Windows / macOS / Linux

"windows": {
  "enabled": true,
  "outputFolder": "../"
}

These targets require C++, emit shared libraries, and generate CMake presets automatically.

Android

"android": {
  "enabled": true,
  "mode": "jni",
  "outputFolder": "../AndroidSource"
}
Mode Description
java Java bridge (source only)
kotlin Kotlin bridge (source only)
jni Pure JNI (C++ native bindings)

Note

jni mode requires C++ bindings. java and kotlin modes generate source only - no native build presets.

Apple Mobile (iOS / tvOS)

"ios": {
  "enabled": true,
  "mode": "native",
  "sourceFolder": "./ios",
  "sourceFilename": "{0}_ios",
  "outputFolder": "../iOSSourceFromMac"
}
Mode Description
objc Objective-C bridge
swift Swift bridge
native Obj-C wrapper over C++ native core

Note

native mode requires C++ bindings.

Consoles

Supported consoles: Xbox, PlayStation 4, PlayStation 5, Nintendo Switch.

"ps5": {
  "enabled": true,
  "outputFolder": "../"
}

Console builds require SDK paths configured in CMakeUserPresets.json (gitignored). See Console Setup for full instructions.

8. Build System Configuration (build)

Controls CMake generation.

"build": {
  "emitCmake": true,
  "cmake": {
    "cppStandard": 20,
    "cppExtensions": false,
    "strictWarnings": true,
    "useThirdParty": true,
    "emitPresets": true
  }
}
Field Description
emitCmake Generate CMakeLists.txt
cppStandard C++ standard (e.g. 17, 20)
cppExtensions Allow compiler extensions
strictWarnings Enable strict compiler warnings
useThirdParty Include third_party directory
emitPresets Generate CMakePresets.json

9. Extras

Documentation

"extras": {
  "docs": {
    "enabled": true,
    "outputFolder": "./docs",
    "outputFileName": "documentation.json",
    "overwrite": true
  }
}

Generates intermediate documentation data consumable by downstream tools for producing user-facing documentation.

10. Path Resolution Rules

All paths:

  • May be relative or absolute
  • root is resolved relative to the config file
  • All other paths are resolved relative to root
  • Support environment variables
  • Support ~ on Unix systems

11. Common Workflows

Full extension generation

extgen --config config.json

Update bindings only

"profile": "BindingsOnly"

Regenerate CMake only

"profile": "BuildOnly"

12. Minimal Example

{
  "input": "./api.gmidl",
  "root": "./",
  "profile": "Full",
  "gml": { "enabled": true },
  "targets": {
    "windows": { "enabled": true },
    "android": { "enabled": true, "mode": "jni" }
  },
  "build": { "emitCmake": true }
}

Notes

  • extgen is target-driven, not language-driven
  • C++ is emitted automatically only when required by the selected targets
  • The JSON Schema is the source of truth - if the schema validates, extgen will run

GameMaker 2026

extgen

Users

Developers

Clone this wiki locally