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 overview (for game code)

• run(game, config?) — Framework entry; config: title, width, height, vsync, resizable, icon.
• IGame: optional init(ctx, config), required update(dt), draw(), optional dispose().
• GameContext: gl, input, width, height.
• Input: ctx.input.mouseX, mouseY, mouseLeft, mouseRight, mouseMiddle, isKeyDown(scancode).
• SCANCODE: e.g. SCANCODE.W, SCANCODE.Escape.
• createDraw2D(gl): clear(r,g,b,a?), fillRect(x,y,w,h,r,g,b,a?), dispose().

For custom rendering, use ctx.gl (WebGL 1) directly.