Particle Realms Engine SDK v0.8.1-alpha.1

Particle Realms Engine SDK — v0.8.1-alpha.1

Engine + Plauna SDK files · README and setup · Download Template.zip

The repository now includes the Engine + Plauna SDK as ordinary files under engine-sdk/: canonical sources, compiled runtime, verified native WASM, runnable examples, offline documentation and Python rebuild tools. Clone this release tag to use the SDK.

Template.zip is the compact starter: one full Platform gzip (Engine, Editor, Plauna, AGI and WebGPU OS), one PhysX PE WASM, and the native/worker support assets needed by its verified operations. Choose WebGPU OS, Plauna Showcase or Blank Canvas. Size: 46.20 MB (44.06 MiB).

Serve over HTTP. In engine-sdk/, run python serve_sdk.py --port 9002 --isolate. Extract Template.zip, enter Template/, and run python serve.py 9002 or launch.bat --port 9002. Open http://127.0.0.1:9002/. Browser modules and runtime fetches require HTTP; opening index.html as a file produces CORS errors.

JavaScript rebuilding uses Python 3.12.7, explicitly installed pinned dependencies and supplied verified native WASM. Offline rebuilding passed without private signing keys. Recompiling PhysX/Blast/Flow or Rust kernels remains a separate native-toolchain workflow.

The exact SDK Git bytes passed source and compiled Engine, worker and Plauna operations at root and nested URLs. Two pinned offline rebuilds produced identical runtime bytes, and a CPU source change executed in the rebuilt runtime. The Template passed all three launch modes, six compiled subsystem examples, real OS service-worker boot, 15 native extension groups including Flow shader delivery, GPU checks and resource cleanup at both mounts. See SDK-VALIDATION.json for exact measured scope and native versions. Experimental capabilities retain their existing status.

Template.zip SHA-256: 22c7b733fc9398a5b8ce605ff2bd191f6b5006ff0e49df54e565f9eb5597ba24

Source-available alpha licensing applies to first-party code; included third-party notices remain authoritative.

alpha

Particle Realms — Platform Template

A copyable starter project for Particle Engine apps, demos, and prototypes.
Ships with a gzipped platform bundle and a 3-mode boot selector.

Quick Start

Template/
├── launch.bat                # Windows launcher: starts server, opens browser
├── serve.py                  # Threaded static server with watchdog restart
├── index.html                # Boot selector + runtime containers
├── README.md                 # This file
└── assets/
    ├── particle-platform.min.js.gz   # Compiled platform bundle (gzip)
    ├── release-runtime-loader.js     # CSP-safe compressed runtime loader
    ├── boot-theme.js                  # Pre-paint theme bootstrap (accent, radius, blur)
    ├── style.css                      # WebGPU OS shell styling
    └── plauna.css                     # Plauna widget framework styling

Launch

Double-click launch.bat — it starts the server and opens
http://127.0.0.1:8000 in your default browser.

Or from the command line:

.\launch.bat
.\launch.bat --port 9001

Or run the server directly:

python serve.py
python serve.py 9001

Then open http://127.0.0.1:8000 in a WebGPU-capable browser (Chrome 113+,
Edge 113+, or any browser with WebGPU support).

Requirements

• Python 3.8+ on PATH
• WebGPU-capable browser (Chrome/Edge 113+ recommended)
• No Node.js or npm — this is a pure browser + Python project

Boot Modes

When the page loads, the runtime bundle is fetched, decompressed, and
SHA-384 verified. Once ready, a selector appears with three choices:

1. WebGPU OS

Boots the full WebGPU OS desktop environment — compositor, kernel, app
registry, taskbar, and window manager. This is the complete OS experience.

• Calls PE.bootWebGpuOS() with canvas, desktop, and taskbar selectors
• Apps and mods are discovered at runtime from apps/ and mods/ folders
• Best for: exploring the OS, running built-in apps, testing compositor

2. Plauna Showcase

Boots the Plauna UI framework and mounts the widget gallery — buttons,
panels, inputs, tabs, toasts, notifications, and more.

• Instantiates ShowcaseApp from the bundle and calls .boot()
• Displays the full widget catalog with live interactive demos
• Best for: previewing UI components, testing widget behavior, design work

3. Blank Canvas

Creates a clean <canvas> element and initializes the raw Particle Engine
on it with no UI shell, no OS, no taskbar — just the rendering surface.

• Accesses PE.Engine and creates an engine instance on a fresh canvas
• Full ECS, rendering, physics, and simulation APIs available via PE
• Best for: prototyping custom apps, rendering experiments, scratch projects

How It Works

Runtime Loader (assets/release-runtime-loader.js)

A CSP-safe loader that:

1. Reads configuration from data-* attributes on its <script> tag
2. Fetches particle-platform.min.js.gz via fetch()
3. Decompresses it using DecompressionStream('gzip')
4. Verifies the decoded byte count matches data-runtime-bytes
5. Verifies SHA-384 integrity against data-integrity
6. Creates a Blob URL and injects it as a <script> tag
7. Exposes the runtime on globalThis.__PE_RUNTIME_READY (a Promise)

Boot Selector (index.html)

After the runtime promise resolves, a mode list appears in the boot card.
Clicking a row dispatches to the appropriate boot function:

Mode	API Call	Container
OS	PE.bootWebGpuOS()	#os-shell
Plauna	new PE.ShowcaseApp(opts).boot()	#plauna-root
Canvas	new PE.Engine({ canvas })	#canvas-root

bootWebGpuOS() manages its own boot status text and removes the loader
overlay internally, so the caller doesn't need to touch the DOM for that
path. The other two modes remove the loader once their boot() call
resolves.

Server (serve.py)

A threaded static file server with:

• COOP/COEP headers on every response, required for WebGPU cross-origin
  isolation (SharedArrayBuffer, high-res timers, etc.)
• Watchdog auto-restart — if the server throws an unhandled exception,
  it restarts automatically with exponential backoff (1s, 2s, 4s... capped
  at 10s) instead of exiting
• Custom port via command-line argument (python serve.py 9001)
• Fails fast with a clear message if the port is already in use

Copy It

Copy-Item -Recurse C:\Coding\game\Template C:\Coding\game\MyPrototype

After copying, update data-integrity and data-runtime-bytes in
index.html if you swap in a different bundle.

The repository-owned Template/ is refreshed automatically after every
successful platform build. The bundler atomically replaces the gzip runtime,
regenerates the loader, copies the manifest, updates integrity and decoded-byte
metadata, and adds a content-derived cache token.

Build a New Bundle

Engine-only runtime:

python bundle_engine.py --target engine --no-cache

Full platform runtime (Engine + Editor + Plauna + AGI + WebGPU OS):

python bundle_engine.py --target platform --no-cache

Output goes to the build directory and Template/ is synchronized
automatically. To refresh an additional standalone compiled-runtime consumer in
the same build, use the repeatable option:

python bundle_engine.py --target platform --no-cache `
  --sync-consumer C:\Coding\Sentenced2Mine

Source-Mode Imports

If your project stays beside the repository engine/ folder, you can
import directly from source instead of using the bundle:

import {
  ENGINE_FULL,
  createWorld,
  createEntity,
  setEntityComponent,
  createTransform,
  stepWorld,
} from '../engine/EngineBootstrap.js';

Rules

• Keep game-specific code in your project folder
• Move code into engine/ only after it is reusable
• Keep public bundle entrypoints side-effect free
• Use Plauna for UI state and Engine/ECS for simulation truth
• Do not import direct engine source from public release pages — use
  compiled PE APIs instead
• Update data-integrity and data-runtime-bytes when swapping bundles

See tests/guide/engine-stack-usage.md for the full stack guide.