user_cli_docs

extgen - User CLI Documentation

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.

This document explains how to use extgen, how to configure it, and what each option does.

---

Table of Contents

1. Overview

2. Installation & Invocation

3. Project Initialization

4. Configuration File Overview

5. Profiles

6. GML Generation

7. Targets (Platforms)

   • Desktop
   • Android
   • Apple Mobile (iOS / tvOS)
   • Consoles

8. Build System Configuration

9. Extras (Documentation)

10. Path Resolution Rules

11. Common Workflows

12. Minimal Examples

---

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 will:

1. 🧾 Generate a JSON Schema describing all supported options
2. 📄 Create a minimal config.json
3. 🔗 Automatically set the $schema property

You can immediately open config.json in any schema-aware editor (VS Code recommended).

---

🗂️ 4. Configuration File Overview

A simplified configuration file looks like this:

{
  "$schema": "./extgen.schema.json",
  "input": "./api.gmidl",
  "root": "./",
  "profile": "Full",
  "gml": { ... },
  "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
gml	GML binding 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"

Available profiles

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

This allows workflows like:

• 🔁 Updating bindings without touching native code
• 🏗️ Regenerating build files only

---

6. GML Generation (gml)

Controls GameMaker binding generation.

"gml": {
  "enabled": true,
  "emitRuntime": true,
  "outputFile": "extension.gml",
  "declarationsFile": "extension_decl.gml",
  "runtimeFilename": "ext_runtime"
}

Options

Field	Description
enabled	Enable GML generation
emitRuntime	Emit the GML runtime support
outputFile	Generated GML API file
declarationsFile	Declaration-only GML file
runtimeFilename	Runtime script base name

Note

GML bindings are typically required for any GameMaker extension. emitRuntime emits the runtime support functions required by generated code (also known as the official GMExtensionCore).

Important

extgen does not create or register assets inside the GameMaker IDE.

• outputFile must point to an existing .gml asset
• declarationsFile is a .yy snippet that must be manually appended to your extension’s .yy file under the functions array

---

🌍 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
• Generate CMake presets automatically

---

Android

"android": {
  "enabled": true,
  "mode": "jni",
  "outputFolder": "../AndroidSource"
}

Modes

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"
}

Modes

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

Example:

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

Nintendo Switch special case

"switch": {
  "enabled": true,
  "userProps": "path/to/user.props",
  "outputFolder": "../"
}

Important

• userProps is required
• extgen does not ship any SDK files
• You must provide your own .props from the Nintendo SDK

---

🏗️ 8. Build System Configuration (build)

Controls CMake generation.

"build": {
  "emitCmake": true,
  "cmake": {
    "cppStandard": 20,
    "cppExtensions": false,
    "strictWarnings": true,
    "useThirdParty": true,
    "emitPresets": true
  }
}

Options

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 that can be consumed by other tools to produce final 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 }
}

---

🧠 Final Notes

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