create-gamenative-app 0.1.1

package/create-gamenative-app/sync-template.js

@@ -0,0 +1,177 @@
+#!/usr/bin/env node
+/**
+ * Sync template from parent GameNative repo. Run from create-gamenative-app/ or before publish.
+ */
+import { mkdir, readFile, writeFile, copyFile } from 'fs/promises'
+import { join, dirname } from 'path'
+import { fileURLToPath } from 'url'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const ROOT = join(__dirname, '..')
+const TEMPLATE = join(__dirname, 'template')
+
+const FRAMEWORK_FILES = [
+  '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',
+  'scripts/copy-config.js',
+]
+
+async function sync() {
+  await mkdir(join(TEMPLATE, 'src', 'games'), { recursive: true })
+  await mkdir(join(TEMPLATE, 'scripts'), { recursive: true })
+  await mkdir(join(TEMPLATE, 'assets'), { recursive: true })
+
+  for (const rel of FRAMEWORK_FILES) {
+    const src = join(ROOT, rel)
+    const dest = join(TEMPLATE, rel)
+    const content = await readFile(src, 'utf-8')
+    await writeFile(dest, content)
+  }
+
+  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 writeFile(join(TEMPLATE, 'src', 'games', 'Game.ts'), gameTemplate)
+
+  try {
+    await copyFile(join(ROOT, 'src', 'assets', 'icon.png'), join(TEMPLATE, 'assets', 'icon.png'))
+  } catch {}
+
+  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'],
+  }
+  await writeFile(join(TEMPLATE, 'tsconfig.json'), JSON.stringify(tsconfig, null, 2))
+
+  const packageJson = {
+    name: '{{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'],
+    },
+  }
+  await writeFile(join(TEMPLATE, 'package.json'), JSON.stringify(packageJson, null, 2))
+
+  const gameConfig = {
+    window: {
+      title: '{{TITLE}}',
+      width: 800,
+      height: 600,
+      icon: 'assets/icon.png',
+    },
+    game: 'Game',
+  }
+  await writeFile(join(TEMPLATE, 'game.config.json'), JSON.stringify(gameConfig, null, 2))
+
+  const readme = `# {{TITLE}}
+
+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.
+`
+  await writeFile(join(TEMPLATE, 'README.md'), readme)
+
+  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(TEMPLATE, 'FRAMEWORK.md'), frameworkMd)
+
+  console.log('Template synced to create-gamenative-app/template/')
+}
+
+sync().catch((err) => {
+  console.error(err)
+  process.exit(1)
+})

package/create-gamenative-app/template/FRAMEWORK.md

@@ -0,0 +1,14 @@
+# 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.

package/create-gamenative-app/template/README.md

@@ -0,0 +1,10 @@
+# {{TITLE}}
+
+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.

package/create-gamenative-app/template/game.config.json

@@ -0,0 +1,9 @@
+{
+  "window": {
+    "title": "{{TITLE}}",
+    "width": 800,
+    "height": 600,
+    "icon": "assets/icon.png"
+  },
+  "game": "Game"
+}

package/create-gamenative-app/template/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "{{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"
+    ]
+  }
+}

package/create-gamenative-app/template/scripts/copy-config.js

@@ -0,0 +1,8 @@
+import { mkdirSync, copyFileSync, existsSync } from 'fs'
+import { join } from 'path'
+const release = join(process.cwd(), 'release')
+mkdirSync(release, { recursive: true })
+const src = join(process.cwd(), 'game.config.json')
+if (existsSync(src)) {
+  copyFileSync(src, join(release, 'game.config.json'))
+}

package/create-gamenative-app/template/src/Game.ts

@@ -0,0 +1,97 @@
+import sdl from '@kmamal/sdl'
+import glPkg from '@kmamal/gl'
+import type { WebGLRenderingContext as GLContext } from '@kmamal/gl'
+import type { IGame, GameConfig, GameContext } from './types.js'
+import { createInput } from './Input.js'
+
+type CreateGL = (width: number, height: number, attrs?: { window?: unknown }) => GLContext
+const createGLContext = (typeof glPkg === 'function' ? glPkg : (glPkg as { default: CreateGL }).default) as CreateGL
+
+const DEFAULT_CONFIG: Required<Omit<GameConfig, 'icon'>> & Pick<GameConfig, 'icon'> = {
+  title: 'Game',
+  width: 800,
+  height: 600,
+  vsync: true,
+  resizable: true,
+}
+
+/**
+ * Runs an IGame: creates SDL window + WebGL context, drives update/draw loop, handles resize and close.
+ */
+export async function run(game: IGame, config: GameConfig = {}): Promise<void> {
+  const opts = { ...DEFAULT_CONFIG, ...config }
+  const window = sdl.video.createWindow({
+    title: opts.title,
+    width: opts.width,
+    height: opts.height,
+    resizable: opts.resizable,
+    vsync: opts.vsync,
+    opengl: true,
+  })
+
+  if (opts.icon) {
+    try {
+      const { loadIcon } = await import('./icon.js')
+      await loadIcon(window as { setIcon: (w: number, h: number, stride: number, format: string, buffer: Buffer) => void }, opts.icon)
+    } catch {
+      // icon optional; ignore if loadIcon or file fails
+    }
+  }
+
+  let width = window.pixelWidth
+  let height = window.pixelHeight
+  const gl = createGLContext(width, height, { window: window.native })
+  const input = createInput(sdl)
+
+  const ctx: GameContext = {
+    gl,
+    input,
+    get width() {
+      return width
+    },
+    get height() {
+      return height
+    },
+  }
+
+  if (game.init) {
+    await game.init(ctx, { ...opts, width, height })
+  }
+
+  window.on('resize', (e: { pixelWidth: number; pixelHeight: number }) => {
+    width = e.pixelWidth
+    height = e.pixelHeight
+    gl.viewport(0, 0, width, height)
+  })
+
+  let running = true
+  window.on('close', () => {
+    running = false
+  })
+
+  let lastTime = performance.now()
+  const maxDt = 0.1
+
+  function loop() {
+    if (!running) {
+      if (game.dispose) game.dispose()
+      window.destroy()
+      return
+    }
+    const now = performance.now()
+    let dt = (now - lastTime) / 1000
+    lastTime = now
+    if (dt > maxDt) dt = maxDt
+
+    game.update(dt)
+    game.draw()
+    gl.swap()
+    setImmediate(loop)
+  }
+
+  setImmediate(loop)
+}
+
+export type { IGame, GameConfig }
+export { sdl, createInput }
+export { SCANCODE } from './Input.js'

package/create-gamenative-app/template/src/Graphics.ts

@@ -0,0 +1,93 @@
+import type { WebGLRenderingContext as GLContext } from '@kmamal/gl'
+
+/**
+ * Minimal 2D helpers: clear, and draw solid-color quads with a simple shader.
+ * For anything else use the raw WebGL context.
+ */
+
+const VERT = `
+attribute vec2 a_position;
+uniform vec2 u_resolution;
+void main() {
+  vec2 clip = (a_position / u_resolution) * 2.0 - 1.0;
+  gl_Position = vec4(clip * vec2(1, -1), 0, 1);
+}
+`
+
+const FRAG = `
+precision mediump float;
+uniform vec4 u_color;
+void main() {
+  gl_FragColor = u_color;
+}
+`
+
+export interface Draw2D {
+  clear(r: number, g: number, b: number, a?: number): void
+  fillRect(x: number, y: number, w: number, h: number, r: number, g: number, b: number, a?: number): void
+  dispose(): void
+}
+
+export function createDraw2D(gl: GLContext): Draw2D {
+  const vs = gl.createShader(gl.VERTEX_SHADER)!
+  gl.shaderSource(vs, VERT)
+  gl.compileShader(vs)
+  if (!gl.getShaderParameter(vs, gl.COMPILE_STATUS)) {
+    throw new Error('vert: ' + gl.getShaderInfoLog(vs))
+  }
+  const fs = gl.createShader(gl.FRAGMENT_SHADER)!
+  gl.shaderSource(fs, FRAG)
+  gl.compileShader(fs)
+  if (!gl.getShaderParameter(fs, gl.COMPILE_STATUS)) {
+    throw new Error('frag: ' + gl.getShaderInfoLog(fs))
+  }
+  const program = gl.createProgram()!
+  gl.attachShader(program, vs)
+  gl.attachShader(program, fs)
+  gl.linkProgram(program)
+  if (!gl.getProgramParameter(program, gl.LINK_STATUS)) {
+    throw new Error('link: ' + gl.getProgramInfoLog(program))
+  }
+
+  const aPosition = gl.getAttribLocation(program, 'a_position')
+  const uResolution = gl.getUniformLocation(program, 'u_resolution')
+  const uColor = gl.getUniformLocation(program, 'u_color')
+
+  const buffer = gl.createBuffer()
+  const verts = new Float32Array(8)
+
+  return {
+    clear(r: number, g: number, b: number, a = 1) {
+      gl.clearColor(r, g, b, a)
+      gl.clear(gl.COLOR_BUFFER_BIT)
+    },
+
+    fillRect(x: number, y: number, w: number, h: number, r: number, g: number, b: number, a = 1) {
+      const x2 = x + w
+      const y2 = y + h
+      verts[0] = x
+      verts[1] = y
+      verts[2] = x2
+      verts[3] = y
+      verts[4] = x
+      verts[5] = y2
+      verts[6] = x2
+      verts[7] = y2
+      gl.bindBuffer(gl.ARRAY_BUFFER, buffer)
+      gl.bufferData(gl.ARRAY_BUFFER, verts, gl.DYNAMIC_DRAW)
+      gl.useProgram(program)
+      gl.uniform2f(uResolution, gl.drawingBufferWidth, gl.drawingBufferHeight)
+      gl.uniform4f(uColor, r, g, b, a)
+      gl.enableVertexAttribArray(aPosition)
+      gl.vertexAttribPointer(aPosition, 2, gl.FLOAT, false, 0, 0)
+      gl.drawArrays(gl.TRIANGLE_STRIP, 0, 4)
+    },
+
+    dispose() {
+      gl.deleteProgram(program)
+      gl.deleteShader(vs)
+      gl.deleteShader(fs)
+      gl.deleteBuffer(buffer)
+    },
+  }
+}

package/create-gamenative-app/template/src/Input.ts

@@ -0,0 +1,83 @@
+/**
+ * Input state: keyboard and mouse. Read each frame in update().
+ * Keys use SDL scancode names; common ones: W, A, S, D, Up, Down, Left, Right, Space, Escape, etc.
+ */
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type SDL = any
+
+export interface InputState {
+  readonly mouseX: number
+  readonly mouseY: number
+  readonly mouseLeft: boolean
+  readonly mouseRight: boolean
+  readonly mouseMiddle: boolean
+  isKeyDown(scancode: number): boolean
+}
+
+export function createInput(sdl: SDL): InputState {
+  const keyboard = sdl.keyboard
+  const mouse = sdl.mouse
+
+  return {
+    get mouseX() {
+      return mouse.position.x
+    },
+    get mouseY() {
+      return mouse.position.y
+    },
+    get mouseLeft() {
+      return mouse.getButton(1)
+    },
+    get mouseRight() {
+      return mouse.getButton(3)
+    },
+    get mouseMiddle() {
+      return mouse.getButton(2)
+    },
+    isKeyDown(scancode: number) {
+      const state = keyboard.getState()
+      return !!(Array.isArray(state) ? state[scancode] : (state as { [k: number]: boolean })[scancode])
+    },
+  }
+}
+
+/** SDL scancode constants for use with input.isKeyDown(sdl.SCANCODE.X). Use the sdl instance from run(). */
+export const SCANCODE = {
+  A: 4,
+  B: 5,
+  C: 6,
+  D: 7,
+  E: 8,
+  F: 9,
+  G: 10,
+  H: 11,
+  I: 12,
+  J: 13,
+  K: 14,
+  L: 15,
+  M: 16,
+  N: 17,
+  O: 18,
+  P: 19,
+  Q: 20,
+  R: 21,
+  S: 22,
+  T: 23,
+  U: 24,
+  V: 25,
+  W: 26,
+  X: 27,
+  Y: 28,
+  Z: 29,
+  Space: 44,
+  Escape: 41,
+  Up: 82,
+  Down: 81,
+  Left: 80,
+  Right: 79,
+  Enter: 40,
+  Shift: 225,
+  Ctrl: 224,
+  Tab: 43,
+} as const

package/create-gamenative-app/template/src/config.ts

@@ -0,0 +1,25 @@
+import { readFile } from 'fs/promises'
+import { join } from 'path'
+
+export interface AppConfig {
+  window?: {
+    title?: string
+    width?: number
+    height?: number
+    icon?: string
+  }
+  /** Game name (no extension). Resolved to src/games/<game>.ts in dev, dist/games/<game>.js in prod. */
+  game?: string
+}
+
+const CONFIG_FILENAME = 'game.config.json'
+
+export async function loadAppConfig(): Promise<AppConfig> {
+  const path = join(process.cwd(), CONFIG_FILENAME)
+  try {
+    const raw = await readFile(path, 'utf-8')
+    return JSON.parse(raw) as AppConfig
+  } catch {
+    return {}
+  }
+}

package/create-gamenative-app/template/src/games/Game.ts

@@ -0,0 +1,32 @@
+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

package/create-gamenative-app/template/src/icon.ts

@@ -0,0 +1,19 @@
+import { readFile } from 'fs/promises'
+import { join } from 'path'
+
+/**
+ * Load a PNG from path and set it as the window icon. Path can be absolute or relative to cwd.
+ */
+export async function loadIcon(
+  window: { setIcon: (w: number, h: number, stride: number, format: string, buffer: Buffer) => void },
+  iconPath: string
+): Promise<void> {
+  const pngjs = await import('pngjs')
+  const PNG = pngjs.default?.PNG ?? pngjs.PNG
+  const abs = join(process.cwd(), iconPath)
+  const buf = await readFile(abs)
+  const png = PNG.sync.read(buf)
+  const stride = png.width * 4
+  const buffer = Buffer.from(png.data)
+  window.setIcon(png.width, png.height, stride, 'rgba32', buffer)
+}

package/create-gamenative-app/template/src/index.ts

@@ -0,0 +1,6 @@
+export { run, sdl, createInput, SCANCODE } from './Game.js'
+export type { IGame, GameConfig } from './Game.js'
+export type { GameContext } from './types.js'
+export type { InputState } from './Input.js'
+export { createDraw2D } from './Graphics.js'
+export type { Draw2D } from './Graphics.js'

package/create-gamenative-app/template/src/main.ts

@@ -0,0 +1,39 @@
+import { pathToFileURL } from 'url'
+import { join, dirname } from 'path'
+import { fileURLToPath } from 'url'
+import { run } from './Game.js'
+import { loadAppConfig } from './config.js'
+import type { IGame } from './types.js'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+
+async function main() {
+  const appConfig = await loadAppConfig()
+  const gameName = appConfig.game ?? 'ExampleGame'
+  const isDev = process.env.NODE_ENV === 'development'
+  const isPkg = typeof (process as { pkg?: unknown }).pkg !== 'undefined'
+  const gamePath =
+    isPkg || !isDev
+      ? join(__dirname, 'games', `${gameName}.js`)
+      : join(process.cwd(), 'src', 'games', `${gameName}.ts`)
+  const href = pathToFileURL(gamePath).href
+
+  const mod = await import(/* @vite-ignore */ href)
+  const game: IGame = mod.default
+  if (!game || typeof game.update !== 'function' || typeof game.draw !== 'function') {
+    throw new Error(`Game "${gameName}" must export a default IGame (update/draw)`)
+  }
+
+  const windowOpts = appConfig.window ?? {}
+  await run(game, {
+    title: windowOpts.title ?? 'Game',
+    width: windowOpts.width ?? 800,
+    height: windowOpts.height ?? 600,
+    icon: windowOpts.icon,
+  })
+}
+
+main().catch((err) => {
+  console.error(err)
+  process.exit(1)
+})

package/create-gamenative-app/template/src/pngjs.d.ts

@@ -0,0 +1,5 @@
+declare module 'pngjs' {
+  export const PNG: {
+    sync: { read(buffer: Buffer): { width: number; height: number; data: Buffer | Uint8Array } }
+  }
+}