game

2-D game toolkit for Lynxer. The drawing, input and window layer is a Rust library built on macroquad, linked into stdlib/game.so and reached through global.game.

Requires: a Rust toolchain (cargo), which is required for the whole build. stdlib/game.so is built by cargo like every other Rust backend; a missing toolchain fails make instead of skipping the module. The Rust source lives in rust/game/; build it with make cargo or make buildLynxer.

Coordinates

World coordinates use bottom-left origin, +Y up, matching the reference game module. The Rust layer flips Y for macroquad internally, and mouse coordinates are reported from the bottom-left. Angles are degrees, counter-clockwise.

Frames and callbacks

run() is blocking. Register the two frame callbacks by name, then call run():

global setup(){ import("game"); }

global onUpdate(float dt){
    // advance the world; dt is seconds since the previous frame
}

global onDraw(){
    global.game.beginDraw();
    global.game.drawRect(100.0, 100.0, 40.0, 40.0, 255, 0, 0);
    global.game.drawText("hello", 10.0, 10.0, 255, 255, 255, 16);
    global.game.endDraw();
}

global main(){
    global.game.init("Demo", 800, 600);
    global.game.setBackground(20, 20, 30);
    global.game.setUpdateCallback("onUpdate");
    global.game.setDrawCallback("onDraw");
    global.game.run();
}

Each frame the module calls onUpdate(dt) and then onDraw(). If either callback raises an error the loop stops and the error is reported at the run() call site. Ctrl-C stops the loop and exits with code 130.

Headless mode

Set LYNXER_GAME_HEADLESS=1 to run without a window. run() then executes a fixed number of deterministic frames (dt = 1/60) and every drawing call is a no-op, so the API and the callback bridge can be tested without a display. The make test fixture runner sets this variable; see examples/stdlib_game.lynx.

Window

Alongside setTitle, setBackground, getWidth/getHeight, setWindowSize, setResizable, setMouseVisible, setFPSCap, getFPS, setFullscreen, hideCursor/showCursor and close:

Lifecycle and timing

Shapes

All colours are int r, g, b (0–255); all coordinates are world coordinates.

coords is a flat "x,y,x,y,..." list and segments a flat "x1,y1,x2,y2,..." list of endpoints. (The reference module took JSON; this backend accepts any non-numeric separator, so "1,2 3,4" and "[1,2,3,4]" both work.)

Text

Input

Key names are case-insensitive: "UP", "DOWN", "LEFT", "RIGHT", "SPACE", "ENTER", "ESCAPE", "TAB", "BACKSPACE", "SHIFT", "CTRL", "ALT", "A"–"Z", "0"–"9", "F1"–"F12". Button names are "LEFT", "RIGHT", "MIDDLE".

Sprites

Sprites are referenced by an integer index (-1 means "not available"). setSpriteVelocity is in pixels per second; updateSprite applies the last frame's deltaTime().

Sprite lists

Textures

Camera

The camera is a transform applied by the draw calls.

Grid helpers

Scenes

A scene is a named collection of sprite lists that are drawn and updated together.

Text labels

Tilemap

loadTilemap(tmxPath, scaling) reads a Tiled .tmx file and returns a scene index; getTilemapLayer(sceneIdx, layerName) returns the named layer as a sprite list. Inline and external TSX tilesets are supported, with global tile IDs mapped to their respective atlas by firstgid, columns, margin and spacing. CSV, XML <tile gid> and base64 layer data (raw, gzip or zlib) are supported. Atlas and TSX image paths are resolved relative to their source files; Tiled horizontal/vertical/diagonal flip flags are retained by tile sprites.

Tiles become solid sprites on the grid, so a map carries geometry and collision (hand a layer to makePhysicsEngine as the wall list). When the atlas cannot be loaded or the module is headless, tiles fall back to shaded blocks.

Physics

A small platformer engine: gravity, wall collision, slopes and one-way platforms.

A step moves the player by vx/vy, pushes them out of the side of a solid wall, applies gravity, and then resolves the landing. Two conventions extend the wall list:

• A wall sprite with a non-zero angle is a slope. Its surface runs from the box's bottom-left corner upward to the right by tan(angle) * width, never above the box's top. Slopes never block horizontal movement.
• A sprite in the one-way list is a platform, solid only for a player who was above it on the previous step and is falling now — so a jump carries the player up through it.

Sprite-to-sprite collision uses oriented bounding boxes based on each sprite's angle. Physics accounts for the rotated player's bounds while preserving the existing wall/slope rules. A grounded player is carried by the platform they landed on when it translates or rotates between physics steps.

The player is snapped onto a slope or platform surface only from within two units of it, which bounds how far a ramp can lift them in one step.

Animation

Both are texture-backed, so in headless mode makeAnimatedSprite returns -1.

Sound

isSoundPlaying queries the rodio sink for current playback state, so completed one-shots and stopped sounds return false, and a queued loop remains active until stopped. loadSound returns -1 in headless mode or when the file or audio output device is unavailable.

Notes and current limitations

The reference's shape batches, animated sprite-sheet helper, setVSync and getDisplaySize are not exposed. makeAnimatedSprite accepts a JSON array of separate image paths rather than a sprite sheet.

Other deviations:

• setResizable is accepted and ignored; setTitle applies when run() opens the window.
• drawPolygon/drawPolyline/drawLines/drawPoints take a flat coordinate string rather than JSON.
• keyCode returns this backend's key code, not Arcade's.
• moveSpriteToward sets velocity in px/s (the reference used px/frame).

Rust / C ABI

The module is a single Rust cdylib (rust/game, crate lynxer_game); there is no C++ shim. It exports lynxer_module_init_v1, every op as cdecl:<ret>(...), and lynxer_module_attach_v1. Macroquad owns the window and event loop, and each frame it invokes the registered Lynxer callbacks through the host API. It uses two additive native-module ABI extensions documented in docs/native-module-abi.md:

• the packed ... signature, which passes any number of numeric/string arguments; and
• the optional lynxer_module_attach_v1 entry point, which provides an invoke callback so a module can call a Lynxer function by name.

See also

• stdlib-contracts — the contract this module implements, including the error sentinel family it uses.
• builtins — the functions the interpreter implements itself.
• limitations — the full divergence register.