GameNative

Native TypeScript framework for desktop games. No game engine — just a thin layer over SDL2 (window, input) and WebGL (via @kmamal/gl) so you write games in TypeScript and run them with Node.

• Window: SDL window with OpenGL, resize, vsync, optional icon.
• Input: Keyboard (scancode-based) and mouse (position + buttons).
• Rendering: Raw WebGL context; optional 2D helper (createDraw2D) for clear + filled rects.
• Loop: Fixed lifecycle: init(ctx) once, then update(dt) and draw() every frame.

Works on Windows, macOS, and Linux (x64; arm64 on Mac).

Install

npm install

Create a new game project (CLI)

Without cloning the repo (recommended):

npx create-gamenative-app@latest

From the GameNative repo (local CLI):

npm run create

A TUI will prompt for project name and directory. It then:

• Creates a new folder with the framework wired up
• Sets game.config.json (window title, size, default icon)
• Adds assets/ and copies the default icon.png
• Adds a starter game at src/games/Game.ts
• Runs npm install in the new project

Then cd <directory>/<project-name> and npm run dev to start. Edit src/games/Game.ts and game.config.json to build your game. The new project includes FRAMEWORK.md (2D, 3D, lighting, assets, sound, UI, camera).

Run (dev)

npm run dev

Runs the app from source with the game and window settings from game.config.json. Edit code and restart to see changes.

Config: game.config.json

At the project root. Controls which game runs and the window.

{
  "window": {
    "title": "My Game",
    "width": 800,
    "height": 600,
    "icon": "assets/icon.png"
  },
  "game": "ExampleGame"
}

• window.title — Window title.
• window.width / height — Window size.
• window.icon — Optional path to a PNG (relative to project root) for window/taskbar icon.
• game — Name of the game to run (no extension). Must match a file under src/games/<name>.ts.

Adding a game

1. Add src/games/MyGame.ts.
2. Export a default object that implements IGame (init?, update(dt), draw(), dispose?).
3. Set "game": "MyGame" in game.config.json.

Example game: src/games/ExampleGame.ts. Escape to exit.

Build and run

npm run build
npm start

Runs the compiled app from dist/ using game.config.json in the current directory.

Build to .exe (Windows)

npm run build:exe

Produces release/GameNative.exe and copies game.config.json into release/. Run the exe from the release/ folder (or put the exe and game.config.json in the same folder). You can change window title, icon path, and game name in that config; the exe includes the default game(s) from dist/games/.

Requires pkg; target is node18-win-x64. For other platforms, adjust the pkg.targets in package.json.

Scripts

| Script | Description | |---------------|--------------------------------------------------| | npm run dev | Run from source (tsx) using game.config.json | | npm run build | Compile TypeScript to dist/ | | npm start | Run dist/main.js (needs game.config.json) | | npm run build:exe | Build then package to release/GameNative.exe |

API reference (everything you need to make a game)

Import from ../../scripts/index.js (or your framework path). All APIs are available in your game file.

Game lifecycle

• run(game, config?) — Starts the framework. Call once from your entry point. config: title, width, height, vsync, resizable, icon.
• IGame — Your game implements: optional init(ctx, config), required update(dt), required draw(), optional dispose().
• GameContext — Passed to init and available each frame: gl (WebGL context), input, width, height (updates on resize).

Input

• ctx.input.mouseX, ctx.input.mouseY — Cursor position in pixels.
• ctx.input.mouseLeft, mouseRight, mouseMiddle — Boolean button state.
• ctx.input.isKeyDown(scancode) — Returns true if key is held. Use SCANCODE for key codes: SCANCODE.W, SCANCODE.A, SCANCODE.S, SCANCODE.D, SCANCODE.Space, SCANCODE.Escape, SCANCODE.Up, SCANCODE.Down, SCANCODE.Left, SCANCODE.Right, SCANCODE.Enter, SCANCODE.Shift, SCANCODE.Ctrl, SCANCODE.Tab, and SCANCODE.A–SCANCODE.Z.

2D drawing (createDraw2D)

• createDraw2D(ctx.gl) — Returns a Draw2D helper. Create once in init, reuse in draw.
• draw2d.clear(r, g, b, a?) — Clear the screen (default a = 1).
• draw2d.fillRect(x, y, w, h, r, g, b, a?) — Filled rectangle in pixels. Origin top-left, y down.
• draw2d.fillTriangles(verts, r, g, b, a?) — Draw triangles. verts is a Float32Array of pixel coords: [x,y, x,y, x,y, ...] (3 vertices per triangle).
• draw2d.strokeRect(x, y, w, h, r, g, b, a?) — 1px outline rectangle (panels, buttons).
• draw2d.dispose() — Call in dispose() to free resources.

Text (fonts, sizes, colors)

• loadFont(path) — Async. Load a TTF/OTF from path (relative to cwd or absolute). Returns a Font.
• drawText(draw2d, font, text, x, y, size, r, g, b, a?) — Draw a string. (x, y) = top-left; y-axis down; size = font size in pixels.
• getTextTriangles(font, text, x, y, size) — Returns Float32Array of triangle vertices. Use with draw2d.fillTriangles(triangles, r, g, b, a) for custom color or caching.
• measureText(font, text, size) — Returns { width, height } in pixels (for layout).

UI / hit-testing

• isPointInRect(px, py, x, y, w, h) — Returns true if point (px, py) is inside the rectangle. Use with ctx.input.mouseX, mouseY, mouseLeft in update() to implement buttons.

Textures (images / sprites)

• loadTexture(gl, path) — Async. Load a PNG from path, upload to a WebGL texture, return { texture, width, height }. You bind and draw with your own shader; the helper only does load + upload.

Raw WebGL — do anything

• ctx.gl — Full WebGL 1 context. No wrapper. Use it for custom shaders, 3D, framebuffers, MSAA, texture arrays, etc. You have full control.

Full SDL — do anything

• sdl — The full @kmamal/sdl module is exported. Use it directly for everything SDL exposes:
  • sdl.video — displays, windows (we create one; you can query others).
  • sdl.keyboard, sdl.mouse, sdl.touch — input (we use keyboard + mouse for ctx.input; you can use more).
  • sdl.audio — sdl.audio.getDevices(), sdl.audio.openDevice(device, options) for playback/recording. Open a device, enqueue buffers (WAV/samples), no high-level helper.
  • sdl.joystick, sdl.controller — gamepads; sdl.sensor — accelerometer/gyro.
  • sdl.clipboard, sdl.power — clipboard, battery.

Node / OS — do anything

• Your game runs in Node.js. You can import 'fs', import 'path', use child_process, native addons, or any npm package. File I/O, save data, scripting, or calling out to other tools — nothing is locked down.

Exports summary

| Export | Purpose | |--------|--------| | run, sdl, createInput, SCANCODE | Entry, full SDL ref, input factory, key codes | | IGame, GameConfig, GameContext | Types for your game and config | | InputState | Type for ctx.input | | createDraw2D, Draw2D | 2D clear/rect/triangles/stroke | | loadFont, drawText, getTextTriangles, measureText, Font | Text rendering | | loadTexture, LoadedTexture | Load PNG → WebGL texture | | isPointInRect | Button/UI hit-test |

Summary: You get raw ctx.gl (WebGL), full sdl (SDL2), and Node (fs, path, etc.). Helpers (draw2D, text, texture load, isPointInRect) are thin conveniences; they don’t hide the native layers. See FRAMEWORK.md in a created project for more detail and a minimal SDL audio example.