generated_output

Generated Output

Running the tool produces up to eight files depending on --lang. All files carry a // auto-generated, DO NOT EDIT header.

---

generated_schemas.gml

One GML constructor function per OpenAPI #/components/schemas object, plus a paired _validate() function.

/// @func GmUser()
/// @param {Real} _id
/// @param {String} _name
/// @param {String} [_email]
function GmUser(_id, _name, _email = undefined) constructor
{
    id    = _id;
    name  = _name;
    email = _email;
}

/// @func GmUser_validate()
/// @param {Struct} _inst
/// @param {String} _where
/// @ignore
function GmUser_validate(_inst, _where = _GMFUNCTION_) {
    _where = $"{_where} :: GmUser_validate";
    // required fields always checked; optional only when defined
    ...
}

Schema mapping rules:

OpenAPI type	GML type
string	String
integer (int32)	Real
integer (int64)	Real
number (float/double)	Real
boolean	Bool
array of T	Array<T>
object with named properties	named struct constructor
object free-form / inline	Struct (any-map)
string with enum	String (enum literals in JSDoc)

oneOf / anyOf / allOf are not yet supported — the IR has a Variant kind but no parser or emitter wiring. These schemas are skipped or collapsed to Struct.

---

generated_http.gml

One public function per OpenAPI operation.

/// @func gm_get_user()
/// @param {Real} _user_id  The user's numeric ID.
/// @param {Function} [_callback]
function gm_get_user(_user_id, _callback = undefined)
{
    static __base_url__ = _gm_options_get_rest_url();

    // argument validation
    ...

    // build url path
    var __url__ = $"{__base_url__}/users/{_user_id}";

    // (no query params for this endpoint)

    return _gm_create_request(__url__, undefined, "GET",
        undefined, undefined, ["bearer"], undefined, _callback, _GMFUNCTION_);
}

Parameter ordering: required parameters come first, then optional ones (defaulting to undefined unless the spec provides a default value).

Parameter locations:

Location	Handling
path	Interpolated directly into the URL string
query	Collected into a _params struct; undefined entries are skipped
header	Injected into the ds_map header inside GmRequest.send()
cookie	Merged with the cookie jar and sent in the Cookie header

Request body:
When an endpoint has a body, a _body parameter is added. If the spec allows multiple content-types, a _content_type parameter is also added (defaulting to the first supported type).

Callback signature:

function(_status, _data, _request)
// _status  {Real}           HTTP status code
// _data    {Struct|Any}     Parsed JSON response (json_parse attempted; raw string on failure)
// _request {Struct.GmRequest}  The request object (supports .retry())

---

generated_helpers.gml

Internal plumbing used by the generated endpoint functions. Contains:

Singleton getter

function _gm_get_singleton(_where) { ... }

Creates obj_gm_core on first call via instance_create_depth(0, 0, 0, obj_gm_core). All state (tokens, jar, requests, hooks) lives on this instance.

Auth token store

gm_request_auth_set_token(_token_id, _token)   // store (public — call this from game code)
_gm_request_auth_get_token(_token_id)           // retrieve (private — used internally)

Body converter registry

gm_request_body_set_converter(_content_type, _function)  // register (public)
_gm_request_body_get_converter(_content_type)             // retrieve (private — used internally)

Response hook registry

gm_request_response_set_hook(_code, _hook)    // register (public — call this from game code)
_gm_request_response_get_hook(_code)          // retrieve (private — used internally)

Cookie jar public API

gm_cookie_set(_name, _value)    // manual write
gm_cookie_get(_name)            // manual read
gm_cookie_delete(_name)         // remove one
gm_cookie_clear()               // wipe jar

GmRequest struct

The internal request wrapper. Created by _gm_create_request() and stored in the singleton's requests ds_map until the Async HTTP event resolves it.

new GmRequest(_url, _params, _method, _body, _content_type, _security, _cookies, _callback, _where)
// Public API:
request.send()           // fire (or re-fire) the HTTP request → returns request id
request.retry()          // alias for send()
request.get_callback()   // return the stored callback function
request.attempts         // integer, increments on each send/retry

---

controller_create.gml (paste into Create event)

Initialises the singleton's state:

// Built-in body converters
type_converters = {};
type_converters[$ "*/*"]                          = function(_i) { return _i; };
type_converters[$ "application/json"]             = function(_i) { return json_stringify(_i, ...); };
type_converters[$ "application/x-www-form-urlencoded"] = function(_i) { return _i; };
type_converters[$ "text/plain"]                   = function(_i) { return string(_i); };
type_converters[$ "multipart/form-data"]          = function(_body, _header) { ... };

auth_tokens     = {};          // scheme name → token string
cookie_jar      = {};          // cookie name → value
requests        = ds_map_create();   // request id → GmRequest
response_hooks  = ds_map_create();   // HTTP status code → hook function

The multipart/form-data converter iterates struct fields and builds a proper MIME multipart body, setting the Content-Type boundary automatically.

The application/json converter uses a replacer to strip undefined struct fields before stringifying, so optional unset parameters are omitted from the JSON payload.

---

controller_http.gml (paste into Async HTTP event)

var _async_id = async_load[? "id"];
var _request  = requests[? _async_id];
if (_request == undefined) exit;

var _status = async_load[? "status"];
if (_status == 1) exit;      // still in progress

// optional debug log (controlled by extension option "debug_logging")
if (_gm_options_is_debug()) { ... }

var _code = async_load[? "http_status"];
var _data = async_load[? "result"];
try { _data = json_parse(_data); } catch(_ex) {}

// auto-capture Set-Cookie into the cookie jar
var _response_headers = async_load[? "response_headers"];
...

// response hook (return true to suppress callback)
var _hook = response_hooks[? _code];
if (is_callable(_hook) && _hook(_code, _data, _request) == true) { ... return; }

// fire callback
var _callback = _request.get_callback();
if (is_callable(_callback)) { _callback(_code, _data, _request); }

ds_map_delete(requests, _async_id);

---

controller_cleanup.gml (paste into Clean Up event)

ds_map_destroy(requests);
ds_map_destroy(response_hooks);

---

schemas_codegen.js and function_codegen.js (--lang docs)

gm-ext-format documentation stubs consumed by the gm-ext updateDocs pipeline. schemas_codegen.js uses @struct_partial / @struct_end blocks; function_codegen.js uses @func_partial / @func_end blocks with @event callback members for the callback signature.

Do not hand-edit these files — regenerate them with --lang docs whenever the spec changes.

---

Response hooks

Hooks intercept responses before the per-request callback fires. Return true to consume the event and suppress the callback:

// Automatically refresh token on 401 and retry
gm_request_response_set_hook(401, function(_code, _data, _request) {
    _refresh_my_token();
    _request.retry();
    return true;   // suppress original callback
});

Custom body converters

Register a converter for a content-type not covered by the defaults:

gm_request_body_set_converter("application/xml", function(_body, _header) {
    // return a string or a buffer
    return my_xml_encode(_body);
});

The converter receives the body value and the ds_map header so it can set (or override) Content-Type — for example the built-in multipart/form-data converter appends the boundary to the header value.