Instruction file imported from scottdreinhart/game-platform (.github/instructions/05-wasm.instructions.md). Copyright stays with the author.

WASM Instructions — AssemblyScript / WebAssembly

Scope: AssemblyScript source, WASM build pipeline, runtime loader, and AI worker integration. Subordinate to AGENTS.md §0 (Non-Negotiable Rules), §6 (language governance), and 01-build.instructions.md. BASELINE: Before building WASM, read AGENTS.md § 0. No parallel build paths. Preserve fallback logic. Bash mandatory.

Overview

The WASM subsystem provides a high-performance AI engine for CPU move computation. AssemblyScript source compiles to WebAssembly, which is embedded as a base64 string and loaded at runtime in a Web Worker.

Shell Governance

Bash (POSIX) is the mandatory shell for all WASM build operations.

• Use Bash (WSL on Windows, native on macOS/Linux) for all WASM builds: pnpm wasm:build, pnpm wasm:build:debug.
• Never use PowerShell for WASM builds.
• See AGENTS.md § 5 (Cross-platform Shell Governance) for complete shell rules.

Architecture

Data flow

apps//assembly/index.ts → (pnpm wasm:build) → build/ai.wasm → base64 → src/wasm/ai-wasm.ts → src/workers/ai.worker.ts → UI organism (postMessage / onmessage)

Scripts

Both scripts run apps/<game-app>/scripts/build-wasm.js which invokes the asc (AssemblyScript compiler) CLI.

Language Boundaries

• AssemblyScript is the only language for WASM source code (apps/<game-app>/assembly/).
• JavaScript is used for the build script (apps/<game-app>/scripts/build-wasm.js).
• TypeScript is used for the runtime loader (src/wasm/ai-wasm.ts) and worker (src/workers/ai.worker.ts).

Do not introduce Rust, C, C++, Go, or other WASM-capable languages unless explicitly requested. Do not create alternative WASM build pipelines outside the existing apps/<game-app>/scripts/build-wasm.js path. Do not manually edit src/wasm/ai-wasm.ts — it is auto-generated by pnpm wasm:build.

Worker Integration

The Web Worker (src/workers/ai.worker.ts) follows a WASM-first strategy:

1. On startup, decode base64 → compile → instantiate WASM module
2. If WASM is available, use it for all move computations
3. If WASM fails (empty base64, compilation error), fall back to JS AI (src/domain/ai.ts)

The worker communicates with the main app organism via postMessage / onmessage. All AI computation runs off the main thread.

Import rules for workers

Workers may only import from @/domain (per AGENTS.md §3). The @/wasm import is permitted as it contains only data (base64 string).

Key Dependencies

Anti-Orphan-Script Policy

Do not create additional WASM build scripts, conversion utilities, or codegen helpers. The single build path is pnpm wasm:build → apps/<game-app>/scripts/build-wasm.js. Any new WASM-related automation must fit within this existing pipeline.