Para Studiodocs

Web target (wasm)

paraloop compiles for the web via Emscripten (wasm + WebGL). The web target is one engine include — src/paraloop/web/paraloop.nims — plus the shell template and webshell assets in the same directory; the repo-root config.nims pulls the nims in for every -d:emscripten build (report §3.3, task 1.7). The nims pins the wasm target; the emscripten -s settings ride on EMCC_CFLAGS (nimscript of this era cannot carry them), and tools/web/postbuild.mjs renders the shell (title/theme) as index.html, lays the webshell assets (manifest, icons) next to the build and writes build.json.

Toolchain: emsdk 6.x (emcc on PATH) plus an official nim >= 2.2.12 — some nimble-managed and distro nim installs ship a config/nim.cfg without the @if emscripten C-compiler wiring and cannot build for this target. nimble webSmoke, para build --target web and para web smoke all build through tools/web/build.sh, which picks the first nim whose config/nim.cfg carries it, trying PARALOOP_WEB_NIM, then the highest install under ~/.nimble/nimbinaries, then nim on PATH, and fails if none does. CI pins PARALOOP_WEB_NIM to the official 2.2.12.

source $EMSDK/emsdk_env.sh          # emcc on PATH (emsdk 6.x), then:

para build --target web --game mygame --title "My Game"
para web pack --game mygame         # tmp/web/mygame-<build id>.zip

Upload the zip's contents to itch.io (an HTML5 project) or any static host.

para build --target web is the shipping build: release (-d:release: on a large game 5.2 MB of wasm against 8.5 MB, and 60 fps at 6x CPU throttle against 15) unless --debug. --define NAME[=VALUE] (repeatable) is passed to nim as -d:NAME[:VALUE] (a game reads it with defined(NAME)), --title is the page title. The output is one directory per game, tmp/web/<game>/ (emptied first, so it holds only this build): index.html (the shell), <game>.js, <game>.wasm, manifest.webmanifest, the two icons and build.json. The build id (<short commit>[-dirty]-<release|debug>[-<define>...], e.g. c2888e8-release-myflag; no timestamp) is in build.json, in the page as <meta name="paraloop-build"> and as small text in its corner (--feedback-url URL adds a "Send feedback" link beside it, with the id appended as ?build=), so a rebuild of the same commit is byte-identical (cold, same toolchain). para web pack zips exactly what a static host needs (index.html, <game>.js, <game>.wasm, the manifest and icons; no build.json) with sorted entries and a fixed time stamp, so the same build always packs to the same bytes; it refuses a -d:dev build. Raw equivalent of the build, which tools/web/build.sh [--debug] [--define D]... SRC OUT wraps (then node tools/web/postbuild.mjs --dir tmp/web/hello --title "paraloop hello"):

EMCC_CFLAGS='-sINVOKE_RUN=1 -sMAX_WEBGL_VERSION=2 -sMIN_WEBGL_VERSION=2 \
             -sSTACK_SIZE=8388608 -sALLOW_MEMORY_GROWTH=1 \
             --pre-js src/paraloop/web/audio.js' \
  nim c -d:emscripten -d:release --hints:off -o:tmp/web/hello/hello examples/hello/hello.nim

or the one-shot task: nimble webSmoke (builds, postbuilds, and smokes examples/hello; it passed only if it wrote tmp/web-smoke-passed). Serve tmp/web/<game>/ with any static file server (no special headers) and open it. --pre-js src/paraloop/web/audio.js is the browser half of web sound (see engine.md, "Sound"); leave it out and the build is silent. -sSINGLE_FILE=1 in EMCC_CFLAGS inlines the wasm for file:// delivery; --theme #rrggbb (or PARALOOP_WEB_THEME) sets the page background and manifest colors.

Input for web games comes through the same emscripten exports a real keyboard and mouse use: Module._psKeyDown/_psKeyUp for keys and Module._psPointer(x, y)/_psButton(button, down) for the pointer (canvas pixels from the top-left, GLFW button numbers; a tap is a left click). The shell's touch controls are optional and show only on touch devices (pointer: coarse): the labelled buttons at the bottom right hold Enter, C, Esc, Tab and M; desktop plays with the keyboard and the mouse. There is no on-screen stick: moving is a tap on the playfield. Touch devices also get a fullscreen toggle (where the Fullscreen API exists) and a dismissible "rotate to landscape" notice in portrait. When the page is hidden or loses focus the shell releases the keys and mouse buttons it holds (it never sends Esc).

Smoke test headless (Node 22+, a Chrome or Chromium binary — the task 1.7 acceptance), directly or wrapped as para web smoke (task 1.8, below):

node tools/web/smoke.mjs --dir tmp/web/hello --game hello [--chrome google-chrome]

The driver serves the build directory, loads the build in a headless Chromium (SwiftShader software WebGL where no GPU is present) and checks over the Chrome DevTools Protocol — no browser-automation package — that the wasm module loads (Module._psKeyDown export present), that ticks run (holding ArrowRight changes the rendered frame, then the game keeps running for --ticks N, default 90), and that there are zero console errors, zero page exceptions and zero WebGL warnings (a texture unit or sampler uniform out of range, any INVALID_*), and that the saved frame is not blank (more than one colour). A game whose title screen ignores the arrows needs --enter (an explicit flag, never auto-detected): the driver taps Enter and waits half a second before its input. --click X,Y (also explicit) posts a real left click at that viewport pixel and checks the canvas receives it and the engine's pointer exports are up: the browser-to-engine path only, not that the game acted on it. --sound is explicit and off by default (the web-smoke CI job passes it for hello): Chromium then also runs under the document-user-activation autoplay policy and the driver checks the Web Audio backend end to end: it loaded its buffers, starts suspended, a real CDP key press (Input.dispatchKeyEvent) moves it to running, and a sound plays after the driver's ArrowRight hold, so the game under test must play a sound on that key (hello does). The page sees a device with --max-texture-units N combined texture units, default 32, the most WebGL2 guarantees, whatever the host's Chromium has: paranim draws textures through a small pool of units (patches/paranim/gl.nim), so a game may create more textures than that. It saves the final frame to tmp/web-smoke/<game>.png. para web smoke builds what ships (release unless --debug, with the same --defines as para build), so it checks the artifact para web pack zips. The web-smoke CI job runs para web smoke --max-texture-units 2 --sound (the default game, which creates more textures than that, so a unit per texture fails it) on every PR that touches the engine, template, tools, examples or build config (the changes job decides; see .github/workflows/ci.yml).