user_gmidl_docs

GMIDL Introduction 🧩

How to Define Your API for extgen

GMIDL (GameMaker Interface Definition Language) is how you describe your extension API.

From one .gmidl file, extgen generates:

• 🎮 GML bindings
• 🧠 C++ bridge code
• 📱 Android glue
• 🍎 iOS / tvOS glue
• 🎮 Console integration
• 🛠 CMake projects

This guide explains GMIDL in the simplest possible way.

---

📚 Table of Contents

1. Basic Structure
2. Attributes
3. Type Rules
4. Using type_hint
5. Collections
6. Optional Types
7. Functions
8. Classes (Structs)
9. Enums
10. Quick Rules Summary
11. Special Types: Functions & Buffers

---

🧱 1. Basic Structure

A GMIDL file looks like this:

[gml_api]
module MyExtension;

// Functions
[global, bind = typed_gml]
function my_function() : unit;

// Classes
[global]
class `[[MyStruct]]` prototype Object
{
    [field]
    property value : string { get; set; }
}

// Enums
[global, bind = typed_gml]
enum MyEnum {
    A,
    B
}

You define:

• Functions
• Classes (structs)
• Enums

---

🏷 2. Attributes (Very Important)

Anything inside brackets [...] is called an attribute.

Example:

[global, bind = typed_gml]
function my_function() : unit;

Attributes can be:

• ✅ Flags → global
• 🔧 Key/value → bind = typed_gml
• 🧠 Type modifiers → type_hint = \...``

Most commonly used attributes:

• global
• bind = typed_gml
• field
• type_hint

---

🧠 3. The Most Important Rule: Types

There are two ways to declare types.

---

✅ A) Normal Types (Direct : type Syntax)

You can write these directly after ::

double
float
int32
uint32
int64
bool
string
object
array
gmval
func
unit (return only)

Example

function add(a: int32, b: int32) : int32;

property name : string;

These are the only types allowed directly.

---

❗ B) Everything Else MUST Use type_hint

You must use type_hint if the type is:

• uint8
• int8
• uint16
• int16
• uint64
• buffer
• Custom enum
• Custom class
• Optional (?)
• Collection ([])
• Fixed-size collection ([X])

The hint must be inside backticks:

type_hint = `...`

---

🧩 4. Using type_hint

Example: uint64

[field, type_hint = `uint64`]
property channel_id : gmval { get; set; }

Notice:

• The visible type stays gmval
• The real type is defined in type_hint

---

Example: Custom Struct

[field, type_hint = `DiscordUserHandle`]
property user : gmval { get; set; }

---

Example: Custom Enum

[field, type_hint = `DiscordStatusType`]
property status : gmval { get; set; }

---

📚 5. Collections (Arrays)

Collections require type_hint.

🔹 Dynamic Array

Use []

[field, type_hint = `uint64[]`]
property participants : gmval { get; set; }

---

🔹 Fixed Size Array

Use [X]

[field, type_hint = `uint8[16]`]
property key : gmval { get; set; }

---

❓ 6. Optional Types

Optionals require type_hint.

Use ?

[field, type_hint = `uint64?`]
property parent_id : gmval { get; set; }

You can combine features:

[field, type_hint = `DiscordUserHandle[]?`]
property users : gmval { get; set; }

---

🧠 7. Functions

Parameters

Parameter types are declared after the parameter name:

function add(a: int32, b: int32) : int32;

If special type required:

function get_user([type_hint = `uint64`] user_id) : gmval;

---

Return Types

Normal types:

function get_count() : int32;

Custom or advanced return type:

[global, bind = typed_gml, type_hint = `DiscordCall`]
function get_call() : gmval;

⚠ Important Rule

What	Where does type_hint go?
Parameter	Next to parameter
Return value	In function attributes

---

🏗 8. Classes (Structs)

Classes represent structured objects returned to GML.

Required Format

[global]
class `[[StructName]]` prototype Object
{
    [field]
    property property_name : type { get; set; }
}

---

🔎 Rules for Classes

1️⃣ Must Have [global]

Classes must always include the global attribute.

---

2️⃣ Name Must Use Special Syntax

The name must:

• Be inside backticks
• Be wrapped in [[ ]]

Example:

class `[[User]]`

This is required for proper symbol resolution.

---

3️⃣ Prototype Must Always Be Object

prototype Object

This is mandatory.

---

4️⃣ Properties Must:

• Use the property keyword
• Be marked with [field]
• Include { get; set; }

Example:

[field, type_hint = `uint64`]
property id : gmval { get; set; }

---

⚠ Important Notes

• Only properties marked [field] are generated.

• { get; set; } is required by the spec.

• extgen does not support custom getters/setters.

• Classes are:

  • 🧠 Native structs in C++
  • 🎮 Constructors in GML

---

🔠 9. Enums

Enums are simple but follow rules.

Required Format

[global, bind = typed_gml]
enum ActivityActionTypes
{
    Invalid = 0,
    Join = 1,
    JoinRequest = 5,
}

---

🔎 Rules for Enums

1️⃣ Must Have [global]

Just like classes and functions.

---

2️⃣ Can Use bind = typed_gml

If you want a strongly-typed GML enum, include:

bind = typed_gml

---

3️⃣ Underlying Type

You can specify underlying type:

enum ErrorCode : int32
{
    None = 0,
    NetworkError = 1
}

Allowed directly:

int32
uint32
int64

If you need something like uint8, you must use type_hint:

[global, type_hint = `uint8`]
enum SmallEnum
{
    A = 0,
    B = 1
}

---

4️⃣ Values Must Be Numeric

Enum members must be integer values.

---

📋 10. Quick Rules Summary

✅ Direct Types Allowed

double
float
int32
uint32
int64
bool
string
object
array
gmval
func
unit

---

❗ Must Use type_hint For

• uint8
• int8
• uint16
• int16
• uint64
• buffer
• Custom enums
• Custom classes
• Arrays ([])
• Fixed arrays ([X])
• Optionals (?)

---

🧩 Syntax Summary

Feature	Syntax
Dynamic array	Type[]
Fixed array	Type[4]
Optional	Type?
Hint required	type_hint = `Type`

---

🎯 Example: Complete Function

[global, bind = typed_gml, type_hint = `DiscordCall`]
function get_call([type_hint = `uint64`] channel_id) : gmval;

What happens:

• channel_id is uint64
• Return type is DiscordCall
• GML receives a typed struct

---

🎯 Final Takeaway

GMIDL is intentionally strict to keep generation predictable.

Follow these steps:

1. Use normal types whenever possible.
2. Use type_hint for everything advanced.
3. Always use backticks in hints.
4. Use [], [X], and ? inside hints.
5. Return type hints go in function attributes.
6. Parameter hints go next to parameters.
7. Classes must follow exact naming rules.
8. Enums must be numeric.

---

⚠️ 11. Special Types in extgen (Functions & Buffers)

This section describes limitations and runtime behavior specific to extgen.

These rules are important.

---

🚫 1. Functions and Buffers Cannot Be Struct Members

In extgen:

❌ You cannot:

• Use func inside a struct/class property
• Use buffer inside a struct/class property
• Return func from a function
• Return buffer from a function

These types are only allowed as function parameters.

---

🧠 2. Functions (func → GMFunction)

In GMIDL:

function do_something(callback: func) : unit;

In native C++ this becomes:

GMFunction

---

🔹 Native API

std::uint64_t getId() const;

template<class... Args>
void call(Args&&... args) const;

---

🔹 How It Works

• Functions are passed from GML into native code.
• They are represented as a lightweight handle.
• You do not need to release them.
• They are automatically cleaned up when they go out of scope.

---

🔹 Calling Back Into GameMaker

You call them like this:

callback.call(123, "hello", myStruct);

You can pass:

• ✅ Numeric scalars
• ✅ Custom structs
• ✅ Custom enums
• ✅ std::string
• ✅ std::string_view
• ✅ const char*

---

🔹 Thread Safety

The call() method is thread-safe.

When called:

• Data is queued internally
• Execution happens in GameMaker’s next frame
• It is safe to call from worker threads

You do not need to handle synchronization.

---

📦 3. Buffers (buffer → GMBuffer)

In GMIDL:

function process_data([type_hint = `buffer`] data) : unit;

When using buffers:

[type_hint = `buffer`]

In native C++ this becomes:

struct GMBuffer {
private:
    void* ptr;
    std::uint64_t size;

public:
    GMBufferReader getReader();
    GMBufferWriter getWriter();

    void* data() const noexcept;
    std::uint64_t length() const noexcept;
};

---

🔹 What GMBuffer Represents

It is a raw memory block passed from GameMaker.

You can:

• Read from it
• Write to it
• Access raw pointer

---

📖 4. Reading From a Buffer

auto reader = buffer.getReader();

You can:

reader.read<T>();
reader.readBytes(ptr, size);

You can safely read:

• Primitive numeric types
• Raw bytes ``

---

✍ 5. Writing To a Buffer

auto writer = buffer.getWriter();

You can:

writer.write<T>(value);
writer.writeBytes(ptr, size);

---

⚠ Important Buffer Limitation

When writing directly to buffers:

❌ You CANNOT write:

• Custom structs
• Custom enums
• Strings
• string_view
• Complex types

You must manually serialize these types into raw bytes.

Buffers are raw memory only.

---

📱 6. Android Representation

On Android (JNI/Java side):

Buffers are represented as:

java.nio.ByteBuffer

This maps directly to the native memory block.

---

🎯 Summary

Type	Allowed as Parameter	Allowed as Struct Field	Allowed as Return
func	✅ Yes	❌ No	❌ No
buffer	✅ Yes	❌ No	❌ No

---

💡 Best Practice

Use:

• func for async callbacks
• buffer for binary payloads only
• Structs for typed data
• Enums for strongly typed states

Avoid mixing buffers with complex type systems.

---

🧩 Why This Restriction Exists

extgen is hybrid:

• Must work in C++
• Must work in GMRT
• Must work in legacy runner
• Must work across all supported platforms

Functions and buffers are runtime primitives, not data structures.

Keeping them parameter-only guarantees:

• Stable ABI
• Cross-platform behavior
• Safe memory ownership

---

This makes the system predictable and safe across all platforms.