create-gamenative-app 0.1.1

package/README.md

@@ -0,0 +1,116 @@
+# GameNative
+
+Native TypeScript framework for desktop games. No game engine — just a thin layer over **SDL2** (window, input) and **WebGL** (via [@kmamal/gl](https://github.com/kmamal/headless-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
+
+```bash
+npm install
+```
+
+## Create a new game project (CLI)
+
+**Without cloning the repo** (recommended):
+
+```bash
+npx create-gamenative-app@latest
+```
+
+**From the GameNative repo** (local CLI):
+
+```bash
+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)
+
+```bash
+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.
+
+```json
+{
+  "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
+
+```bash
+npm run build
+npm start
+```
+
+Runs the compiled app from `dist/` using `game.config.json` in the current directory.
+
+## Build to .exe (Windows)
+
+```bash
+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](https://github.com/vercel/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.

package/bin/create.js

@@ -0,0 +1,255 @@
+#!/usr/bin/env node
+import inquirer from 'inquirer'
+import { mkdir, writeFile, copyFile, readFile } from 'fs/promises'
+import { join, dirname } from 'path'
+import { fileURLToPath } from 'url'
+import { spawn } from 'child_process'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const FRAMEWORK_ROOT = join(__dirname, '..')
+
+function kebab(s) {
+  return s
+    .trim()
+    .replace(/\s+/g, '-')
+    .replace(/[^a-zA-Z0-9-]/g, '')
+    .toLowerCase() || 'my-game'
+}
+
+async function copyFrameworkFile(relPath) {
+  return readFile(join(FRAMEWORK_ROOT, relPath), 'utf-8')
+}
+
+async function scaffold(projectName, parentDir) {
+  const name = kebab(projectName)
+  const projectPath = join(parentDir, name)
+  const src = join(projectPath, 'src')
+  const games = join(projectPath, 'src', 'games')
+  const assets = join(projectPath, 'assets')
+  const scripts = join(projectPath, 'scripts')
+
+  await mkdir(projectPath, { recursive: true })
+  await mkdir(games, { recursive: true })
+  await mkdir(assets, { recursive: true })
+  await mkdir(scripts, { recursive: true })
+
+  const [
+    mainTs,
+    configTs,
+    gameTs,
+    inputTs,
+    graphicsTs,
+    typesTs,
+    indexTs,
+    iconTs,
+    pngjsDts,
+    copyConfigJs,
+  ] = await Promise.all([
+    copyFrameworkFile('src/main.ts'),
+    copyFrameworkFile('src/config.ts'),
+    copyFrameworkFile('src/Game.ts'),
+    copyFrameworkFile('src/Input.ts'),
+    copyFrameworkFile('src/Graphics.ts'),
+    copyFrameworkFile('src/types.ts'),
+    copyFrameworkFile('src/index.ts'),
+    copyFrameworkFile('src/icon.ts'),
+    copyFrameworkFile('src/pngjs.d.ts'),
+    readFile(join(FRAMEWORK_ROOT, 'scripts/copy-config.js'), 'utf-8'),
+  ])
+
+  const gameConfig = {
+    window: {
+      title: projectName.trim() || name,
+      width: 800,
+      height: 600,
+      icon: 'assets/icon.png',
+    },
+    game: 'Game',
+  }
+
+  const packageJson = {
+    name,
+    version: '0.1.0',
+    description: `Game built with GameNative`,
+    type: 'module',
+    main: 'dist/main.js',
+    scripts: {
+      dev: 'cross-env NODE_ENV=development tsx src/main.ts',
+      build: 'tsc',
+      start: 'node dist/main.js',
+      'build:exe': 'npm run build && node scripts/copy-config.js && pkg . --output release/' + name + '.exe',
+    },
+    dependencies: {
+      '@kmamal/gl': '^9.1.0',
+      '@kmamal/sdl': '^0.11.13',
+      pngjs: '^7.0.0',
+    },
+    devDependencies: {
+      '@types/node': '^22.10.0',
+      cross-env: '^7.0.3',
+      pkg: '^5.8.1',
+      tsx: '^4.19.2',
+      typescript: '^5.7.0',
+    },
+    engines: { node: '>=18' },
+    pkg: {
+      scripts: 'dist/main.js',
+      assets: ['node_modules/@kmamal/sdl/**', 'node_modules/@kmamal/gl/**', 'dist/games/**'],
+      targets: ['node18-win-x64'],
+    },
+  }
+
+  const tsconfig = {
+    compilerOptions: {
+      target: 'ES2022',
+      module: 'NodeNext',
+      moduleResolution: 'NodeNext',
+      outDir: 'dist',
+      rootDir: '.',
+      strict: true,
+      declaration: true,
+      declarationMap: true,
+      sourceMap: true,
+      skipLibCheck: true,
+      esModuleInterop: true,
+      forceConsistentCasingInFileNames: true,
+    },
+    include: ['src/**/*.ts'],
+    exclude: ['node_modules', 'dist'],
+  }
+
+  const gameTemplate = `import { createDraw2D, SCANCODE } from '../index.js'
+import type { GameContext, IGame } from '../types.js'
+
+interface Game extends IGame {
+  ctx: GameContext | null
+  draw2d: ReturnType<typeof createDraw2D> | null
+}
+
+const game: Game = {
+  ctx: null,
+  draw2d: null,
+
+  async init(ctx: GameContext) {
+    this.ctx = ctx
+    this.draw2d = createDraw2D(ctx.gl)
+  },
+
+  update(dt: number) {
+    if (this.ctx?.input.isKeyDown(SCANCODE.Escape)) process.exit(0)
+  },
+
+  draw() {
+    this.draw2d?.clear(0.08, 0.08, 0.12, 1)
+    this.draw2d?.fillRect(100, 100, 120, 80, 0.2, 0.5, 0.9, 1)
+  },
+
+  dispose() {
+    this.draw2d?.dispose()
+  },
+}
+
+export default game
+`
+
+  await Promise.all([
+    writeFile(join(projectPath, 'package.json'), JSON.stringify(packageJson, null, 2)),
+    writeFile(join(projectPath, 'tsconfig.json'), JSON.stringify(tsconfig, null, 2)),
+    writeFile(join(projectPath, 'game.config.json'), JSON.stringify(gameConfig, null, 2)),
+    writeFile(join(src, 'main.ts'), mainTs),
+    writeFile(join(src, 'config.ts'), configTs),
+    writeFile(join(src, 'Game.ts'), gameTs),
+    writeFile(join(src, 'Input.ts'), inputTs),
+    writeFile(join(src, 'Graphics.ts'), graphicsTs),
+    writeFile(join(src, 'types.ts'), typesTs),
+    writeFile(join(src, 'index.ts'), indexTs),
+    writeFile(join(src, 'icon.ts'), iconTs),
+    writeFile(join(src, 'pngjs.d.ts'), pngjsDts),
+    writeFile(join(games, 'Game.ts'), gameTemplate),
+    writeFile(join(scripts, 'copy-config.js'), copyConfigJs),
+  ])
+
+  const iconSrc = join(FRAMEWORK_ROOT, 'src', 'assets', 'icon.png')
+  try {
+    await copyFile(iconSrc, join(assets, 'icon.png'))
+  } catch {
+    // no icon if missing
+  }
+
+  const readme = `# ${projectName.trim() || name}
+
+Game built with [GameNative](https://github.com/your-org/GameNative).
+
+- \`npm run dev\` — run from source
+- \`npm run build\` then \`npm start\` — run built app
+- Edit \`game.config.json\` for window title, size, icon
+- Edit \`src/games/Game.ts\` to build your game
+
+See FRAMEWORK.md for 2D, 3D, lighting, sound, UI, and camera.
+`
+  const frameworkMd = `# GameNative capabilities
+
+Your game has access to:
+
+- **2D**: \`createDraw2D(ctx.gl)\` — \`clear()\`, \`fillRect()\`. Use \`ctx.gl\` (WebGL 1) for textures, sprites, batching.
+- **3D**: Use \`ctx.gl\` directly: buffers, shaders, matrices. Implement camera (view/projection), meshes, and lighting in shaders.
+- **Lighting**: In 3D shaders use uniforms for light position/color; in 2D use tint or custom fragment shaders.
+- **Assets**: Load images (decode PNG with pngjs or similar), upload to \`ctx.gl\` textures; load audio (see sound).
+- **Sound**: \`ctx.sdl.audio\` (SDL audio) — open device, enqueue buffers. Or add a small wrapper in your game.
+- **Visuals**: Full WebGL — post-process by rendering to framebuffer, then to screen; particles, blur, etc. in shaders.
+- **UI**: Draw quads with \`fillRect\` or textured quads; track \`ctx.input.mouseX/Y\` and \`mouseLeft\` for clicks; implement panels/buttons in \`update\`/\`draw\`.
+- **Camera**: 2D: store \`offsetX, offsetY, scale\` and pass to your draw calls or a uniform. 3D: \`view\` and \`projection\` matrices from position/target/up and perspective.
+
+All of this is done in your \`Game.ts\` using \`ctx.gl\`, \`ctx.input\`, and optional helpers you add.
+`
+  await writeFile(join(projectPath, 'README.md'), readme)
+  await writeFile(join(projectPath, 'FRAMEWORK.md'), frameworkMd)
+
+  return { projectPath: projectPath, name }
+}
+
+function npmInstall(cwd) {
+  return new Promise((resolve, reject) => {
+    const isWin = process.platform === 'win32'
+    const child = spawn(isWin ? 'npm.cmd' : 'npm', ['install'], {
+      cwd,
+      stdio: 'inherit',
+      shell: isWin,
+    })
+    child.on('close', (code) => (code === 0 ? resolve() : reject(new Error('npm install failed'))))
+  })
+}
+
+async function main() {
+  console.log('\n  GameNative — create a new game project\n')
+  const answers = await inquirer.prompt([
+    {
+      type: 'input',
+      name: 'projectName',
+      message: 'Project name:',
+      default: 'my-game',
+      validate: (v) => (v?.trim() ? true : 'Enter a name'),
+    },
+    {
+      type: 'input',
+      name: 'directory',
+      message: 'Create project in directory:',
+      default: '.',
+    },
+  ])
+  const dir = answers.directory?.trim() || '.'
+  const resolvedDir = join(process.cwd(), dir)
+  console.log('\n  Creating project...')
+  const { projectPath, name } = await scaffold(answers.projectName, resolvedDir)
+  console.log('  Installing dependencies...')
+  await npmInstall(projectPath)
+  console.log('\n  Done!\n')
+  console.log('  Next:\n')
+  console.log(`    cd ${dir}/${name}`)
+  console.log('    npm run dev\n')
+}
+
+main().catch((err) => {
+  console.error(err)
+  process.exit(1)
+})

package/create-gamenative-app/README.md

@@ -0,0 +1,33 @@
+# create-gamenative-app
+
+Scaffold a new [GameNative](https://github.com/your-org/GameNative) desktop game project.
+
+## Usage
+
+```bash
+npx create-gamenative-app@latest
+```
+
+You’ll be prompted for **project name** and **directory**. The CLI creates the project, installs dependencies, and copies the default window icon into `assets/`.
+
+Then:
+
+```bash
+cd <directory>/<project-name>
+npm run dev
+```
+
+## Publish (maintainers)
+
+From the GameNative repo:
+
+1. Update framework code in `src/`, `scripts/`, etc. as needed.
+2. From `create-gamenative-app/`: run `node sync-template.js` to refresh `template/` from the parent repo (or rely on `prepublishOnly`).
+3. Bump version in `create-gamenative-app/package.json`, then:
+
+   ```bash
+   cd create-gamenative-app
+   npm publish
+   ```
+
+Users can then run `npx create-gamenative-app@latest` to get the new template.

package/create-gamenative-app/index.js

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+import inquirer from 'inquirer'
+import { mkdir, readFile, writeFile, copyFile } from 'fs/promises'
+import { join, dirname } from 'path'
+import { fileURLToPath } from 'url'
+import { spawn } from 'child_process'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const TEMPLATE_DIR = join(__dirname, 'template')
+
+function kebab(s) {
+  return s
+    .trim()
+    .replace(/\s+/g, '-')
+    .replace(/[^a-zA-Z0-9-]/g, '')
+    .toLowerCase() || 'my-game'
+}
+
+const TEMPLATE_FILES = [
+  'package.json',
+  'tsconfig.json',
+  'game.config.json',
+  'README.md',
+  'FRAMEWORK.md',
+  'src/main.ts',
+  'src/config.ts',
+  'src/Game.ts',
+  'src/Input.ts',
+  'src/Graphics.ts',
+  'src/types.ts',
+  'src/index.ts',
+  'src/icon.ts',
+  'src/pngjs.d.ts',
+  'src/games/Game.ts',
+  'scripts/copy-config.js',
+]
+
+async function scaffold(projectName, parentDir) {
+  const name = kebab(projectName)
+  const title = projectName.trim() || name
+  const projectPath = join(parentDir, name)
+
+  await mkdir(projectPath, { recursive: true })
+  await mkdir(join(projectPath, 'src', 'games'), { recursive: true })
+  await mkdir(join(projectPath, 'scripts'), { recursive: true })
+  await mkdir(join(projectPath, 'assets'), { recursive: true })
+
+  for (const rel of TEMPLATE_FILES) {
+    const src = join(TEMPLATE_DIR, rel)
+    const dest = join(projectPath, rel)
+    const content = await readFile(src, 'utf-8')
+    const out = content.replace(/\{\{NAME\}\}/g, name).replace(/\{\{TITLE\}\}/g, title)
+    await writeFile(dest, out)
+  }
+
+  try {
+    await copyFile(join(TEMPLATE_DIR, 'assets', 'icon.png'), join(projectPath, 'assets', 'icon.png'))
+  } catch {}
+
+  return { projectPath, name }
+}
+
+function npmInstall(cwd) {
+  return new Promise((resolve, reject) => {
+    const isWin = process.platform === 'win32'
+    const child = spawn(isWin ? 'npm.cmd' : 'npm', ['install'], {
+      cwd,
+      stdio: 'inherit',
+      shell: isWin,
+    })
+    child.on('close', (code) => (code === 0 ? resolve() : reject(new Error('npm install failed'))))
+  })
+}
+
+async function main() {
+  console.log('\n  GameNative — create a new game project\n')
+  const answers = await inquirer.prompt([
+    {
+      type: 'input',
+      name: 'projectName',
+      message: 'Project name:',
+      default: 'my-game',
+      validate: (v) => (v?.trim() ? true : 'Enter a name'),
+    },
+    {
+      type: 'input',
+      name: 'directory',
+      message: 'Create project in directory:',
+      default: '.',
+    },
+  ])
+  const dir = answers.directory?.trim() || '.'
+  const resolvedDir = join(process.cwd(), dir)
+  console.log('\n  Creating project...')
+  const { projectPath, name } = await scaffold(answers.projectName, resolvedDir)
+  console.log('  Installing dependencies...')
+  await npmInstall(projectPath)
+  console.log('\n  Done!\n')
+  console.log('  Next:\n')
+  console.log(`    cd ${dir}/${name}`)
+  console.log('    npm run dev\n')
+}
+
+main().catch((err) => {
+  console.error(err)
+  process.exit(1)
+})

package/create-gamenative-app/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "create-gamenative-app",
+  "version": "0.1.0",
+  "description": "Scaffold a new GameNative desktop game project",
+  "type": "module",
+  "main": "index.js",
+  "bin": {
+    "create-gamenative-app": "./index.js"
+  },
+  "files": [
+    "index.js",
+    "template"
+  ],
+  "scripts": {
+    "prepublishOnly": "node sync-template.js"
+  },
+  "dependencies": {
+    "inquirer": "^9.2.23"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "gamenative",
+    "game",
+    "sdl",
+    "webgl",
+    "typescript",
+    "scaffold",
+    "create-app"
+  ],
+  "license": "MIT"
+}