bevy-ts 0.1.0-alpha.2 → 0.1.0-alpha.3

package/bin/bevy-ts.js

@@ -1,10 +1,18 @@
 #!/usr/bin/env node
 // Runs the precompiled engine binary from the platform package npm installed alongside this one
 // (as esbuild and Biome ship), so `npx bevy-ts dev src/game.ts` needs no Rust toolchain.
-// BEVY_TS_BINARY overrides the binary, for engine development.
+// BEVY_TS_BINARY overrides the binary, for engine development. `new` and `examples` run here, in
+// Node, with no engine.
 import { spawn } from "node:child_process";
+import { create, examples } from "./examples.js";
 import { binary } from "./resolve.js";
 
+// exitCode, not exit(): stdout to a pipe is written asynchronously and must drain first.
+const [command, ...rest] = process.argv.slice(2);
+if (command === "new") process.exitCode = create(rest);
+else if (command === "examples") process.exitCode = examples(rest);
+else runEngine();
+
 function binaryOrExit() {
   try {
     return binary();
@@ -14,11 +22,13 @@ function binaryOrExit() {
   }
 }
 
-// Forward signals so stopping the launcher stops the engine too.
-const child = spawn(binaryOrExit(), process.argv.slice(2), { stdio: "inherit" });
-for (const sig of ["SIGINT", "SIGTERM", "SIGHUP"]) process.on(sig, () => child.kill(sig));
-child.on("error", (e) => {
-  console.error(`bevy-ts: ${e.message}`);
-  process.exit(1);
-});
-child.on("exit", (code, signal) => process.exit(code ?? (signal ? 1 : 0)));
+function runEngine() {
+  // Forward signals so stopping the launcher stops the engine too.
+  const child = spawn(binaryOrExit(), process.argv.slice(2), { stdio: "inherit" });
+  for (const sig of ["SIGINT", "SIGTERM", "SIGHUP"]) process.on(sig, () => child.kill(sig));
+  child.on("error", (e) => {
+    console.error(`bevy-ts: ${e.message}`);
+    process.exit(1);
+  });
+  child.on("exit", (code, signal) => process.exit(code ?? (signal ? 1 : 0)));
+}

package/bin/examples.js

@@ -0,0 +1,141 @@
+// `bevy-ts examples` and `bevy-ts new`: the launcher's own commands. They read the examples this
+// package ships (copied in at pack time by scripts/sync-examples.mjs) and never start the engine.
+import { spawnSync } from "node:child_process";
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { basename, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = fileURLToPath(new URL("../examples/", import.meta.url));
+const version = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+// What `new` leaves out of the copy: the metadata, not the game.
+const META = ["example.json", "thumbnail.png"];
+
+/** The shipped examples, in the order to show them: `cube` first, then by id. */
+export function list() {
+  if (!existsSync(root)) return [];
+  const out = [];
+  for (const name of readdirSync(root)) {
+    const file = `${root}${name}/example.json`;
+    if (!existsSync(file)) continue;
+    const { id, title, description, entry } = JSON.parse(readFileSync(file, "utf8"));
+    const e = { id, title, description, entry };
+    if (existsSync(`${root}${name}/thumbnail.png`)) e.thumbnail = `${root}${name}/thumbnail.png`;
+    e.dir = `${root}${name}`;
+    out.push(e);
+  }
+  return out.sort((a, b) => (a.id === "cube" ? -1 : b.id === "cube" ? 1 : a.id < b.id ? -1 : 1));
+}
+
+function refuse(msg, code = 1) {
+  console.error(`bevy-ts: ${msg}`);
+  return code;
+}
+
+export function examples(args) {
+  const all = list().map(({ dir, ...e }) => e);
+  if (args.includes("--json")) {
+    process.stdout.write(`${JSON.stringify({ version, examples: all })}\n`);
+  } else {
+    for (const e of all) console.log(`${e.id.padEnd(10)} ${e.title}: ${e.description}`);
+  }
+  return 0;
+}
+
+const NEW_USAGE = "usage: bevy-ts new <dir> [--example <id>] [--no-install] [--json]";
+
+export function create(args) {
+  let dir;
+  let id = "cube";
+  let install = true;
+  let json = false;
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === "--example") {
+      id = args[++i];
+      if (!id || id.startsWith("--")) return refuse(`--example takes an id\n${NEW_USAGE}`, 2);
+    } else if (a === "--no-install") install = false;
+    else if (a === "--json") json = true;
+    else if (a.startsWith("--")) return refuse(`unknown option ${a}\n${NEW_USAGE}`, 2);
+    else if (dir === undefined) dir = a;
+    else return refuse(`unexpected argument ${a}\n${NEW_USAGE}`, 2);
+  }
+  if (dir === undefined) return refuse(`missing <dir>\n${NEW_USAGE}`, 2);
+
+  // Everything is checked before the first write, so a refusal writes nothing.
+  const all = list();
+  const example = all.find((e) => e.id === id);
+  if (!example) return refuse(`no example "${id}"; there are: ${all.map((e) => e.id).join(", ")}`);
+  const target = resolve(dir);
+  if (existsSync(target)) {
+    if (!statSync(target).isDirectory()) return refuse(`${target} is a file`);
+    if (readdirSync(target).length) return refuse(`${target} is not empty; bevy-ts new makes a project only in an empty or missing directory`);
+  }
+
+  try {
+    mkdirSync(target, { recursive: true });
+    for (const f of readdirSync(example.dir)) {
+      if (!META.includes(f)) cpSync(`${example.dir}/${f}`, `${target}/${f}`, { recursive: true });
+    }
+    const name = basename(target).toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^[._-]+/, "") || "game";
+    const pkg = {
+      name,
+      private: true,
+      type: "module",
+      scripts: { dev: `bevy-ts dev ${example.entry}` },
+      devDependencies: { "bevy-ts": version },
+    };
+    // The examples' compiler options, resolving bevy-ts from node_modules instead of the checkout.
+    const tsconfig = {
+      compilerOptions: {
+        target: "es2023",
+        module: "esnext",
+        moduleResolution: "bundler",
+        strict: true,
+        noEmit: true,
+        verbatimModuleSyntax: true,
+        jsx: "react-jsx",
+        jsxImportSource: "bevy-ts",
+        allowImportingTsExtensions: true,
+      },
+      include: ["src", ".bevy-ts/types"],
+    };
+    writeFileSync(`${target}/package.json`, `${JSON.stringify(pkg, null, 2)}\n`);
+    writeFileSync(`${target}/tsconfig.json`, `${JSON.stringify(tsconfig, null, 2)}\n`);
+    writeFileSync(`${target}/.gitignore`, "node_modules/\n.bevy-ts/\n");
+  } catch (e) {
+    return refuse(e.message);
+  }
+
+  const pm = packageManager();
+  const installed = install ? runInstall(pm, target) : false;
+  if (json) {
+    process.stdout.write(`${JSON.stringify({ dir: target, entry: example.entry, example: id, installed })}\n`);
+  } else {
+    console.log(`Made ${target} from ${id}${install && !installed ? "; the install failed" : ""}.`);
+    const steps = [`cd ${shellQuote(dir)}`, ...(installed ? [] : [`${pm} install`]), `npx bevy-ts dev ${example.entry}`];
+    console.log(`  ${steps.join(" && ")}`);
+  }
+  return install && !installed ? 1 : 0;
+}
+
+/** The package manager that ran bevy-ts (npm, pnpm, yarn or bun), npm otherwise. */
+function packageManager() {
+  const agent = (process.env.npm_config_user_agent ?? "").split("/")[0];
+  return ["npm", "pnpm", "yarn", "bun"].includes(agent) ? agent : "npm";
+}
+
+/** The path as it pastes into a POSIX shell: single-quoted when it holds anything but safe characters. */
+function shellQuote(p) {
+  return /^[\w@%+=:,./-]+$/.test(p) ? p : `'${p.replaceAll("'", "'\\''")}'`;
+}
+
+/** Installs with `pm` in `dir`, its output on stderr. */
+function runInstall(pm, dir) {
+  console.error(`bevy-ts: ${pm} install in ${dir}`);
+  const r = spawnSync(pm, ["install"], { cwd: dir, stdio: ["ignore", 2, 2], shell: process.platform === "win32" });
+  if (r.error || r.status !== 0) {
+    console.error(`bevy-ts: ${pm} install failed${r.error ? `: ${r.error.message}` : ""}; the project is in place, run it again there`);
+    return false;
+  }
+  return true;
+}

package/examples/arena/assets/levels/arena.bsn

@@ -0,0 +1,18 @@
+// The arena: where things are. What an enemy is lives in src/enemy.tsx.
+
+#EnemyA
+@enemy::Enemy
+Transform { translation: Vec3 { x: -3.0, z: -4.0 } }
+--
+#EnemyB
+@enemy::Enemy { @hp: 250.0 }
+Transform { translation: Vec3 { x: 3.0, z: -4.0 } }
+--
+// Two copies of one room, each with its guard.
+#RoomA
+:"levels/room.bsn"
+Transform { translation: Vec3 { x: -12.0, z: -12.0 } }
+--
+#RoomB
+:"levels/room.bsn"
+Transform { translation: Vec3 { x: 12.0, z: -12.0 } }

package/examples/arena/assets/levels/room.bsn

@@ -0,0 +1,8 @@
+// A room, placed twice by arena.bsn: its guard is an enemy too.
+#Room
+Transform
+Children [
+    #Guard
+    @enemy::Enemy { @hp: 50.0 }
+    Transform { translation: Vec3 { z: -16.0 } }
+]

package/examples/arena/assets/models/crate.gltf

@@ -0,0 +1,103 @@
+{
+  "accessors": [
+    {
+      "bufferView": 0,
+      "componentType": 5126,
+      "count": 24,
+      "max": [
+        0.5,
+        0.5,
+        0.5
+      ],
+      "min": [
+        -0.5,
+        -0.5,
+        -0.5
+      ],
+      "type": "VEC3"
+    },
+    {
+      "bufferView": 1,
+      "componentType": 5126,
+      "count": 24,
+      "type": "VEC3"
+    },
+    {
+      "bufferView": 2,
+      "componentType": 5123,
+      "count": 36,
+      "type": "SCALAR"
+    }
+  ],
+  "asset": {
+    "generator": "bevy-ts-viewport tests/assets.rs",
+    "version": "2.0"
+  },
+  "bufferViews": [
+    {
+      "buffer": 0,
+      "byteLength": 288,
+      "byteOffset": 0
+    },
+    {
+      "buffer": 0,
+      "byteLength": 288,
+      "byteOffset": 288
+    },
+    {
+      "buffer": 0,
+      "byteLength": 72,
+      "byteOffset": 576
+    }
+  ],
+  "buffers": [
+    {
+      "byteLength": 648,
+      "uri": "data:application/octet-stream;base64,AAAAPwAAAL8AAAC/AAAAPwAAAD8AAAC/AAAAPwAAAD8AAAA/AAAAPwAAAL8AAAA/AAAAvwAAAL8AAAA/AAAAvwAAAD8AAAA/AAAAvwAAAD8AAAC/AAAAvwAAAL8AAAC/AAAAvwAAAD8AAAC/AAAAvwAAAD8AAAA/AAAAPwAAAD8AAAA/AAAAPwAAAD8AAAC/AAAAvwAAAL8AAAA/AAAAvwAAAL8AAAC/AAAAPwAAAL8AAAC/AAAAPwAAAL8AAAA/AAAAvwAAAL8AAAA/AAAAPwAAAL8AAAA/AAAAPwAAAD8AAAA/AAAAvwAAAD8AAAA/AAAAPwAAAL8AAAC/AAAAvwAAAL8AAAC/AAAAvwAAAD8AAAC/AAAAPwAAAD8AAAC/AACAPwAAAAAAAAAAAACAPwAAAAAAAAAAAACAPwAAAAAAAAAAAACAPwAAAAAAAAAAAACAvwAAAAAAAAAAAACAvwAAAAAAAAAAAACAvwAAAAAAAAAAAACAvwAAAAAAAAAAAAAAAAAAgD8AAAAAAAAAAAAAgD8AAAAAAAAAAAAAgD8AAAAAAAAAAAAAgD8AAAAAAAAAAAAAgL8AAAAAAAAAAAAAgL8AAAAAAAAAAAAAgL8AAAAAAAAAAAAAgL8AAAAAAAAAAAAAAAAAAIA/AAAAAAAAAAAAAIA/AAAAAAAAAAAAAIA/AAAAAAAAAAAAAIA/AAAAAAAAAAAAAIC/AAAAAAAAAAAAAIC/AAAAAAAAAAAAAIC/AAAAAAAAAAAAAIC/AAABAAIAAAACAAMABAAFAAYABAAGAAcACAAJAAoACAAKAAsADAANAA4ADAAOAA8AEAARABIAEAASABMAFAAVABYAFAAWABcA"
+    }
+  ],
+  "materials": [
+    {
+      "name": "wood",
+      "pbrMetallicRoughness": {
+        "baseColorFactor": [
+          0.55,
+          0.36,
+          0.18,
+          1.0
+        ],
+        "metallicFactor": 0.0,
+        "roughnessFactor": 0.8
+      }
+    }
+  ],
+  "meshes": [
+    {
+      "name": "crate",
+      "primitives": [
+        {
+          "attributes": {
+            "NORMAL": 1,
+            "POSITION": 0
+          },
+          "indices": 2,
+          "material": 0
+        }
+      ]
+    }
+  ],
+  "nodes": [
+    {
+      "mesh": 0,
+      "name": "crate"
+    }
+  ],
+  "scene": 0,
+  "scenes": [
+    {
+      "nodes": [
+        0
+      ]
+    }
+  ]
+}

package/examples/arena/example.json

@@ -0,0 +1,6 @@
+{
+  "id": "arena",
+  "title": "Arena",
+  "description": "A player and a HUD in TSX, enemies placed by a level file, and systems that bob, hurt and cull them.",
+  "entry": "src/game.tsx"
+}

package/examples/arena/src/enemy.tsx

@@ -0,0 +1,28 @@
+// What an enemy is: a scene component. Levels place it (assets/levels/arena.bsn writes
+// `@enemy::Enemy { @hp: 250.0 }`), and TSX can mount it too (`<Enemy at={[0, 0, -6]} />`).
+import { Component, SceneComponent, type f32, type Vec3Like } from "bevy-ts";
+import { Transform } from "bevy-ts/bevy";
+
+export class Health extends Component {
+  hp: f32 = 100;
+  max: f32 = 100;
+}
+/** Marks enemies, for the systems that move and cull them. */
+export class Foe extends Component {}
+
+export class Enemy extends SceneComponent {
+  static scene({ hp = 100, at = [0, 0, 0] }: { hp?: f32; at?: Vec3Like }) {
+    return (
+      <entity name="enemy">
+        <Transform translation={at} />
+        <Health initialHp={hp} max={hp} />
+        <Foe />
+        <mesh shape="cuboid" size={[1, 1, 1]} color="#cc3333" />
+        <entity key="eye">
+          <Transform translation={[0, 0.6, 0.5]} />
+          <mesh shape="sphere" radius={0.15} color="#ffffff" />
+        </entity>
+      </entity>
+    );
+  }
+}

package/examples/arena/src/game.tsx

@@ -0,0 +1,52 @@
+// The arena: a player and a HUD in TSX, the enemies placed by assets/levels/arena.bsn, a camera, and
+// three systems that play. `bevy-ts dev src/game.tsx`.
+import { app, type Commands, type Entity, type Local, type Mut, type Query, ref, type Res, Startup, Time, Transform, type u32, Update, type With, type Without } from "bevy-ts";
+import { Foe, Health } from "./enemy.tsx";
+import { Hud } from "./hud.tsx";
+import { Player, PlayerUnit } from "./player.tsx";
+
+/** The game's camera and light. The camera sits where the editor's first view does, so edit mode
+ * opens on the same view. */
+export function stage(commands: Commands) {
+  commands.spawnNative("camera3d", { position: [-6, 5, 10], lookAt: [0, 0, 0] });
+  commands.spawnNative("directionalLight", { position: [3, 6, 2], lookAt: [0, 0, 0] });
+}
+
+/** Every 30 frames, each enemy within 10 units hurts the player by 5. */
+export function damage(
+  clock: Local<{ frames: u32 }>,
+  enemies: Query<[Transform], With<Foe>>,
+  players: Query<[Transform, Mut<Health>], With<Player>>,
+) {
+  clock.frames += 1;
+  if (clock.frames % 30 !== 0) return;
+  players.each((p, h) => {
+    enemies.each((e) => {
+      if (e.translation.distance(p.translation) < 10) h.hp = Math.max(0, h.hp - 5);
+    });
+  });
+}
+
+/** Enemies bob up and down. */
+export function bob(time: Res<Time>, enemies: Query<[Mut<Transform>], [With<Foe>, Without<Player>]>) {
+  enemies.each((t) => {
+    t.translation.y = Math.sin(time.elapsed_secs * 2) * 0.5;
+  });
+}
+
+/** Enemies at no hp are despawned: a reload does not bring them back. */
+export function cull(commands: Commands, enemies: Query<[Entity, Health], With<Foe>>) {
+  enemies.each((e, h) => {
+    if (h.hp <= 0) commands.entity(e).despawn();
+  });
+}
+
+const player = ref();
+app.scene("arena", () => (
+  <>
+    <PlayerUnit handle={player} />
+    <Hud player={player} />
+  </>
+));
+app.level("levels/arena.bsn");
+app.addSystems(Startup, stage).addSystems(Update, damage, bob, cull);

package/examples/arena/src/hud.tsx

@@ -0,0 +1,12 @@
+// The HUD: no hooks. The text binds the player's Health; the button mounts an enemy.
+import { type NodeRef, px } from "bevy-ts";
+import { Enemy, Health } from "./enemy.tsx";
+
+export const Hud = ({ player }: { player: NodeRef }) => (
+  <node style={{ position: "absolute", top: px(12), left: px(12), padding: px(8), flexDirection: "column", rowGap: px(6) }} background="#00000088">
+    <text key="hp" size={20}>{() => `HP ${Math.ceil(player.get(Health).hp)} / ${player.get(Health).max}`}</text>
+    <button key="spawn" style={{ padding: px(4) }} background="#3366cc" onPointerClick={({ commands, frame }) => commands.mount(<Enemy key={`e${frame}`} at={[0, 0, -6]} />)}>
+      <text>Spawn</text>
+    </button>
+  </node>
+);

package/examples/arena/src/player.tsx

@@ -0,0 +1,14 @@
+import { Component, type NodeRef } from "bevy-ts";
+import { Transform } from "bevy-ts/bevy";
+import { Health } from "./enemy.tsx";
+
+export class Player extends Component {}
+
+export const PlayerUnit = ({ handle }: { handle: NodeRef }) => (
+  <entity name="player" ref={handle}>
+    <Transform translation={[0, 0, 0]} />
+    <Health initialHp={100} max={100} />
+    <Player />
+    <mesh shape="sphere" radius={0.5} color="#3366cc" />
+  </entity>
+);

package/examples/cube/example.json

@@ -0,0 +1,6 @@
+{
+  "id": "cube",
+  "title": "Cube",
+  "description": "One cube bobbing on a sine wave: a component, a startup system and an update system.",
+  "entry": "src/game.ts"
+}

package/examples/cube/src/game.ts

@@ -0,0 +1,22 @@
+import { app, Component, type f32, Startup, Time, Transform, Update } from "bevy-ts";
+import type { Commands, Mut, Query, Res } from "bevy-ts";
+
+export class Mover extends Component {
+  speed: f32 = 1;
+  amplitude: f32 = 2;
+}
+
+export function scene(commands: Commands) {
+  commands.spawnNative("camera3d", { position: [-3, 3, 6], lookAt: [0, 0, 0] });
+  commands.spawnNative("directionalLight", { position: [3, 6, 2], lookAt: [0, 0, 0] });
+  const cube = commands.spawnNative("cuboid", { size: [1, 1, 1], color: "#f80" });
+  commands.entity(cube).insert(Mover.of());
+}
+
+export function bob(time: Res<Time>, q: Query<[Mover, Mut<Transform>]>) {
+  q.each((mover, t) => {
+    t.translation.y = Math.sin(time.elapsed_secs * mover.speed) * mover.amplitude;
+  });
+}
+
+app.addSystems(Startup, scene).addSystems(Update, bob);

package/examples/cube/src/glow.tsx

@@ -0,0 +1,18 @@
+// The cube example with a script material (bevy-ts/material): its params in TS, its shader in
+// glow.wgsl, no Rust. Run this file as the entry: `bevy-ts dev examples/cube/src/glow.tsx`.
+// Save glow.wgsl and the cube redraws with no reload; change the params and it re-encodes.
+import "./game.ts";
+import { app } from "bevy-ts";
+import { Transform } from "bevy-ts/bevy";
+import { color, f32, material } from "bevy-ts/material";
+import glow from "./glow.wgsl";
+
+export const Glow = material("game::Glow", { params: { color: color, pulse: f32 }, fragment: glow });
+
+app.scene("glow", () => (
+  <entity name="glow">
+    <Transform translation={[2.5, 0, 0]} />
+    <mesh shape="cuboid" size={[1, 1, 1]} />
+    <material kind={Glow} color="#ff8800" pulse={2} />
+  </entity>
+));

package/examples/cube/src/glow.wgsl

@@ -0,0 +1,13 @@
+// game::Glow's fragment shader. bevy-ts appends `params` (a GlowParams with color and pulse)
+// from the schema in glow.tsx, so this file does not declare it.
+import bevy_pbr::render::forward_io::VertexOutput;
+import bevy_pbr::render::mesh_view_bindings::globals;
+
+const FLOOR: f32 = 0.25;
+
+@fragment
+fn fragment(in: VertexOutput) -> @location(0) vec4<f32> {
+    let wave = 0.5 + 0.5 * sin(globals.time * params.pulse);
+    let glow = FLOOR + (1.0 - FLOOR) * wave;
+    return vec4<f32>(params.color.rgb * glow, params.color.a);
+}

package/index.d.ts

@@ -1,3 +1,4 @@
+/// <reference path="./wgsl.d.ts" />
 // Types for `bevy-ts`: the ruled surface (operator, 2026-10-20; docs/research/dx.md). The runtime
 // is built into the engine binary.
 //
@@ -427,6 +428,8 @@ export interface App {
 
 /** Writes a manifest section for a Rust plugin. */
 export declare function section(name: string, value: Uint8Array | string | object): void;
+/** The loading generation's `{ items }` list for a JSON section, for a built-in module's per-generation declarations. */
+export declare function sectionItems(name: string): unknown[];
 /** Decodes UTF-8 bytes. */
 export declare function text(bytes: Uint8Array): string;
 /** A plugin: an exported function taking the app, as Bevy's `fn build(&self, app: &mut App)`. */

package/jsx-runtime.d.ts

@@ -132,6 +132,17 @@ export interface MaterialProps {
   roughness?: number;
   emissive?: string;
   unlit?: boolean;
+  kind?: never;
+}
+
+/**
+ * `<material kind={Glow} color="#f80" pulse={2} />`: a script material from `material()` in
+ * `bevy-ts/material`, with its params by name and its textures as asset paths. Checked against
+ * the kind's schema when the generation loads.
+ */
+export interface ScriptMaterialProps {
+  kind: { readonly name: string };
+  [param: string]: unknown;
 }
 
 type DescElement = Element;
@@ -161,7 +172,7 @@ export declare namespace JSX {
   interface IntrinsicElements {
     entity: EntityProps & KeyAttribute;
     mesh: MeshProps;
-    material: MaterialProps;
+    material: MaterialProps | ScriptMaterialProps;
     node: NodeProps & KeyAttribute;
     button: NodeProps & KeyAttribute;
     text: TextProps & KeyAttribute;

package/material.d.ts

@@ -0,0 +1,61 @@
+// @generated from crates/bevy-ts-material/ts/material.d.ts by scripts/sync-runtime.mjs. Do not edit.
+/** The value a `.wgsl` import gives: the file, by path. Its WGSL stays in the engine. */
+export interface ShaderFile {
+  readonly kind: "shaderFile";
+  readonly path: string;
+}
+
+export type Base = "f32" | "i32" | "u32" | "vec2f" | "vec3f" | "vec4f" | "mat4x4f" | "color";
+export type ParamType = Base | { readonly array: Base; readonly len: number };
+
+export declare const f32: "f32";
+export declare const i32: "i32";
+export declare const u32: "u32";
+export declare const vec2f: "vec2f";
+export declare const vec3f: "vec3f";
+export declare const vec4f: "vec4f";
+export declare const mat4x4f: "mat4x4f";
+/** A `vec4<f32>` in linear RGBA, written as `"#f80"` or sRGB `[r, g, b, a?]`. */
+export declare const color: "color";
+/** A 2D texture with a filtering sampler: `name` and `name_sampler` in WGSL. */
+export declare const texture2d: "texture2d";
+
+/** A fixed array, strided to 16 bytes; scalar and `vec2f` elements read as `.x`/`.xy` of a `vec4`. */
+export declare function array<B extends Base, N extends number>(of: B, len: N): { readonly array: B; readonly len: N };
+
+export type AlphaMode = "opaque" | "blend" | "premultiplied" | "add" | "multiply" | "alphaToCoverage" | { mask: number };
+
+/** A param's value in TS: numbers, number tuples, or a color. */
+export type ParamValue<T extends ParamType> = T extends "f32" | "i32" | "u32"
+  ? number
+  : T extends "vec2f"
+    ? [number, number]
+    : T extends "vec3f"
+      ? [number, number, number]
+      : T extends "vec4f"
+        ? [number, number, number, number]
+        : T extends "mat4x4f"
+          ? number[]
+          : T extends "color"
+            ? string | [number, number, number] | [number, number, number, number]
+            : T extends { array: infer E extends Base }
+              ? ParamValue<E>[]
+              : never;
+
+/** A material kind, what `<material kind={...} />` names. */
+export interface MaterialKind<P extends Record<string, ParamType> = Record<string, ParamType>, T extends Record<string, "texture2d"> = {}> {
+  readonly name: string;
+  /** Types only: the params and textures `<material>` takes for this kind. */
+  readonly __props?: { [K in keyof P]?: ParamValue<P[K]> } & { [K in keyof T]?: string };
+}
+
+/**
+ * Declares a script material: its params, laid out by WGSL's uniform rules in Rust; its textures;
+ * and its shaders, `.wgsl` files imported like modules (`import glow from "./glow.wgsl"`). The WGSL
+ * reads the params as `params.<name>` and each texture as `<name>` with `<name>_sampler`; bevy-ts
+ * appends those declarations, so the file does not declare them.
+ */
+export declare function material<P extends Record<string, ParamType>, T extends Record<string, "texture2d"> = {}>(
+  name: string,
+  decl: { params: P; textures?: T; fragment: ShaderFile; vertex?: ShaderFile; alphaMode?: AlphaMode },
+): MaterialKind<P, T>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bevy-ts",
-  "version": "0.1.0-alpha.2",
+  "version": "0.1.0-alpha.3",
   "description": "TypeScript for Bevy: components, systems and hot reload without recompiling Rust",
   "license": "MIT OR Apache-2.0",
   "repository": {
@@ -30,6 +30,10 @@
       "types": "./jsx-dev-runtime.d.ts",
       "default": "./runtime/jsx-dev-runtime.js"
     },
+    "./material": {
+      "types": "./material.d.ts",
+      "default": "./runtime/material.js"
+    },
     "./protocol": {
       "types": "./protocol.d.ts"
     },
@@ -51,14 +55,14 @@
     "*.js",
     "bin",
     "runtime",
-    "plugins"
+    "plugins",
+    "examples"
   ],
   "optionalDependencies": {
-    "@bevy-ts/darwin-arm64": "0.1.0-alpha.2",
-    "@bevy-ts/darwin-x64": "0.1.0-alpha.2",
-    "@bevy-ts/linux-arm64": "0.1.0-alpha.2",
-    "@bevy-ts/linux-x64": "0.1.0-alpha.2",
-    "@bevy-ts/win32-x64": "0.1.0-alpha.2"
+    "@bevy-ts/darwin-arm64": "0.1.0-alpha.3",
+    "@bevy-ts/darwin-x64": "0.1.0-alpha.3",
+    "@bevy-ts/linux-arm64": "0.1.0-alpha.3",
+    "@bevy-ts/linux-x64": "0.1.0-alpha.3"
   },
   "devDependencies": {
     "json-schema-to-typescript": "^15.0.4",
@@ -67,7 +71,8 @@
   },
   "scripts": {
     "check": "node scripts/sync-runtime.mjs --check && tsc -p ../../examples/cube && tsc -p test",
-    "test": "vitest run --config test/vitest/vitest.config.mjs"
+    "prepack": "node scripts/sync-examples.mjs",
+    "test": "node scripts/sync-examples.mjs && vitest run --config test/vitest/vitest.config.mjs"
   },
   "publishConfig": {
     "access": "public",

package/plugins/esbuild.js

@@ -5,6 +5,11 @@ export default function bevyTs() {
   return {
     name: "bevy-ts",
     setup(build) {
+      // A `.wgsl` import is a shader-file value, as in the engine; the WGSL is not loaded.
+      build.onLoad({ filter: /\.wgsl$/ }, (args) => ({
+        contents: `export default Object.freeze({ kind: "shaderFile", path: ${JSON.stringify(args.path)} });\n`,
+        loader: "js",
+      }));
       build.onLoad({ filter: /\.(c|m)?tsx?$/ }, (args) => {
         if (args.path.includes("/node_modules/")) return undefined;
         return { contents: transform(args.path), loader: "js" };

package/plugins/vite.js

@@ -6,6 +6,12 @@ export default function bevyTs() {
   return {
     name: "bevy-ts",
     enforce: "pre",
+    // A `.wgsl` import is a shader-file value, as in the engine; the WGSL is not loaded.
+    load(id) {
+      // `./x.wgsl?raw` and `?url` keep Vite's own meaning.
+      if (!id.endsWith(".wgsl")) return null;
+      return `export default Object.freeze({ kind: "shaderFile", path: ${JSON.stringify(id)} });\n`;
+    },
     transform(code, id) {
       const file = id.split("?")[0];
       if (!TS_FILE.test(file) || file.includes("/node_modules/")) return null;

package/protocol.d.ts

@@ -1,7 +1,7 @@
 // @generated by packages/bevy-ts/scripts/gen-protocol.mjs from protocol/bevy-ts.openrpc.json. Do not edit.
 
 /** The protocol version these types describe. */
-export const PROTOCOL_VERSION: "1.10.0";
+export const PROTOCOL_VERSION: "1.16.0";
 
 /**
  * An entity id: Entity::to_bits.
@@ -203,7 +203,10 @@ export type LevelOp =
        * A name path from the file's top; `#n` is the n-th unnamed sibling.
        */
       parent: string[];
-      name: string;
+      /**
+       * Optional (1.12): without it the writer picks the first free sibling name.
+       */
+      name?: string;
       /**
        * add_instance: the scene component.
        */
@@ -224,6 +227,10 @@ export type LevelOp =
           [k: string]: LevelValue;
         };
       }[];
+      /**
+       * add_entity (1.12): a .glb or .gltf path, written as WorldAssetRoot("path#Scene0"), or a .bsn to include.
+       */
+      asset?: string;
     }
   | {
       op: "delete";
@@ -250,6 +257,10 @@ export type LevelOp =
        * A name path from the file's top; `#n` is the n-th unnamed sibling.
        */
       parent: string[];
+      /**
+       * (1.12) The place among the parent's written children; last when absent.
+       */
+      index?: number;
     }
   | {
       op: "restore";
@@ -259,6 +270,32 @@ export type LevelOp =
       parent: string[];
       index: number;
       text: string;
+    }
+  | {
+      op: "add_component";
+      /**
+       * A name path from the file's top; `#n` is the n-th unnamed sibling.
+       */
+      path: string[];
+      /**
+       * As LevelOverride.component names it, or any path a .bsn patch resolves.
+       */
+      component: string;
+      fields?: {
+        [k: string]: LevelValue;
+      };
+      /**
+       * The patch as written; the inverse of a remove_component carries it.
+       */
+      text?: string;
+    }
+  | {
+      op: "remove_component";
+      /**
+       * A name path from the file's top; `#n` is the n-th unnamed sibling.
+       */
+      path: string[];
+      component: string;
     };
 
 /**
@@ -503,7 +540,19 @@ export interface TsSchemaExtension {
   };
 }
 /**
- * A component's schema in the shape stock registry.schema uses, plus x-bevy-ts for TS components.
+ * How an editor treats a component: whose it is, whether the engine maintains it, whether Add component may offer it, and its icon category.
+ *
+ * This interface was referenced by `ProtocolTypes`'s JSON-Schema
+ * via the `definition` "EditorInfo".
+ */
+export interface EditorInfo {
+  origin: "engine" | "game" | "plugin";
+  internal: boolean;
+  addable: boolean;
+  category: "transform" | "render" | "light" | "camera" | "physics" | "audio" | "ui" | "animation" | "game" | "other";
+}
+/**
+ * A component's schema in the shape stock registry.schema uses, plus x-bevy-ts for TS components and x-bevy-ts-editor for every component.
  *
  * This interface was referenced by `ProtocolTypes`'s JSON-Schema
  * via the `definition` "ComponentSchema".
@@ -519,6 +568,7 @@ export interface ComponentSchema {
   required?: string[];
   reflectTypes?: string[];
   "x-bevy-ts"?: TsSchemaExtension;
+  "x-bevy-ts-editor"?: EditorInfo;
   [k: string]: unknown;
 }
 /**
@@ -758,6 +808,28 @@ export interface TsxTreeNode {
    * Despawned by something other than tsx; not respawned until a restart or a key change.
    */
   tombstoned: boolean;
+  /**
+   * (1.12) Set when a level placed the entity; absent for a TSX-only node.
+   */
+  level?: {
+    /**
+     * The outermost level file (a sidecar's path for a scene overlay).
+     */
+    file: string;
+    namePath: string[];
+    /**
+     * Written in that file, rather than coming from a prefab, an included level or the scene's TSX.
+     */
+    written: boolean;
+  };
+  /**
+   * (1.15) The root the node is in.
+   */
+  root?: string;
+  /**
+   * (1.15) The node id of the nearest ancestor row, or null at the root's top. Slot steps (`<Show>`, `<For>`) are in the key path but are not rows.
+   */
+  parent?: TsxNodeId | null;
 }
 /**
  * This interface was referenced by `ProtocolTypes`'s JSON-Schema
@@ -767,6 +839,10 @@ export interface TsxRoot {
   name: string;
   location?: SourceLocation | null;
   nodes: TsxTreeNode[];
+  /**
+   * (1.12) An app.scene root's sidecar level path, whether or not the file exists.
+   */
+  sidecar?: string;
 }
 /**
  * This interface was referenced by `ProtocolTypes`'s JSON-Schema
@@ -867,7 +943,7 @@ export interface TsxMoved {
   source: SourceLocation | null;
 }
 /**
- * The first message carries `snapshot`; later ones carry one reconcile's changes: nodes added, removed, tombstoned, whose source moved, and whose values tsx wrote. A gap in `seq` means resubscribe.
+ * The first message carries `snapshot`; later ones carry one reconcile's changes: nodes added, removed, tombstoned, whose source moved, whose values tsx wrote, and sibling lists whose order changed. A client that applies `added` and `removed`, then replaces each `ordered` parent's children with `children`, holds the tree `tsx_tree` returns. A gap in `seq` means resubscribe.
  *
  * This interface was referenced by `ProtocolTypes`'s JSON-Schema
  * via the `definition` "TsxTreeWatchMessage".
@@ -876,10 +952,31 @@ export interface TsxTreeWatchMessage {
   seq: number;
   snapshot?: TsxRoot[];
   added?: TsxTreeNode[];
+  /**
+   * Every node gone, its whole subtree included (1.15).
+   */
   removed?: TsxNodeId[];
   tombstoned?: TsxNodeId[];
   moved?: TsxMoved[];
   written?: TsxNodeId[];
+  /**
+   * (1.15) Each sibling list that gained a child, lost one or changed order since the last message, with its full order as `tsx_tree` gives it. A list whose parent was removed is not sent.
+   */
+  ordered?: TsxOrdered[];
+}
+/**
+ * One sibling list's full child order.
+ *
+ * This interface was referenced by `ProtocolTypes`'s JSON-Schema
+ * via the `definition` "TsxOrdered".
+ */
+export interface TsxOrdered {
+  root: string;
+  /**
+   * The list's parent row, or null for the root's top.
+   */
+  parent: TsxNodeId | null;
+  children: TsxNodeId[];
 }
 /**
  * Modifier keys held; absent means up.
@@ -1356,6 +1453,11 @@ export interface PickHit {
   entity: Entity;
   depth: number;
   selects: Entity;
+  /**
+   * @minItems 3
+   * @maxItems 3
+   */
+  point?: [number, number, number];
 }
 /**
  * This interface was referenced by `ProtocolTypes`'s JSON-Schema
@@ -1363,6 +1465,11 @@ export interface PickHit {
  */
 export interface ViewportPickResult {
   hits: PickHit[];
+  /**
+   * @minItems 3
+   * @maxItems 3
+   */
+  ground?: [number, number, number] | null;
 }
 /**
  * Entities, or a source location resolved as bevy-ts/tsx_find resolves it.
@@ -1571,6 +1678,7 @@ export interface AssetInfo {
   loadState: AssetLoadState;
   error?: string | null;
   labels?: string[];
+  thumbnail?: boolean;
 }
 /**
  * This interface was referenced by `ProtocolTypes`'s JSON-Schema
@@ -1807,6 +1915,10 @@ export interface LevelNodeResult {
    * A scene component instance's @props, beside its fields; empty for anything else. (1.7)
    */
   props?: LevelProp[];
+  /**
+   * (1.12) Components the file adds that the entity's prefab does not give, named as LevelOverride.component names them.
+   */
+  patches?: string[];
 }
 /**
  * One @prop of a scene component instance: its type, the value it takes, and whether the level sets it.
@@ -1848,7 +1960,10 @@ export interface SourceLocation1 {
 export interface LevelWriteParams {
   id?: number;
   file: string;
-  base: LevelHash;
+  /**
+   * null (1.12): the file does not exist yet.
+   */
+  base: LevelHash | null;
   ops: LevelOp[];
 }
 /**
@@ -1877,6 +1992,13 @@ export interface LevelWriteResult {
    * The batch that undoes this one.
    */
   inverse: LevelOp[];
+  /**
+   * (1.12) One per entity the batch added, in order; entity is null when the level is not open.
+   */
+  created?: {
+    namePath: string[];
+    entity: Entity | null;
+  }[];
 }
 /**
  * This interface was referenced by `ProtocolTypes`'s JSON-Schema
@@ -2031,6 +2153,43 @@ export interface AssetPreviewCloseParams {
 export interface AssetPreviewCloseResult {
   closed: boolean;
 }
+/**
+ * This interface was referenced by `ProtocolTypes`'s JSON-Schema
+ * via the `definition` "LevelCatalogResult".
+ */
+export interface LevelCatalogResult {
+  scenes: LevelCatalogScene[];
+}
+/**
+ * This interface was referenced by `ProtocolTypes`'s JSON-Schema
+ * via the `definition` "LevelCatalogScene".
+ */
+export interface LevelCatalogScene {
+  name: string;
+  file?: string | null;
+  line?: number | null;
+  props: LevelCatalogProp[];
+}
+/**
+ * This interface was referenced by `ProtocolTypes`'s JSON-Schema
+ * via the `definition` "LevelCatalogProp".
+ */
+export interface LevelCatalogProp {
+  name: string;
+  /**
+   * The prop's type as the manifest writes it ({ "kind": "f32" }).
+   */
+  type: {
+    [k: string]: unknown;
+  };
+  /**
+   * The literal default, or null.
+   */
+  default: {
+    [k: string]: unknown;
+  };
+  required: boolean;
+}
 
 /** Every method: params, result, owning crate, and whether it streams. */
 export interface Methods {
@@ -2073,6 +2232,7 @@ export interface Methods {
   "bevy-ts/asset_preview_close": { params: AssetPreviewCloseParams; result: AssetPreviewCloseResult; crate: "bevy-ts-viewport"; watch: false };
   "bevy-ts/level_list": { params: undefined; result: LevelListResult; crate: "bevy-ts-levels"; watch: false };
   "bevy-ts/level_node": { params: LevelNodeParams; result: LevelNodeResult; crate: "bevy-ts-levels"; watch: false };
+  "bevy-ts/level_catalog": { params: undefined; result: LevelCatalogResult; crate: "bevy-ts-levels"; watch: false };
   "bevy-ts/level_write": { params: LevelWriteParams; result: LevelWriteResult; crate: "bevy-ts-levels"; watch: false };
   "bevy-ts/level_apply": { params: LevelApplyParams; result: LevelApplyResult; crate: "bevy-ts-levels"; watch: false };
   "bevy-ts/level+watch": { params: undefined; result: LevelWatchMessage; crate: "bevy-ts-levels"; watch: true };

package/runtime/core.js

@@ -849,6 +849,21 @@ export function section(name, value) {
   g.sections.set(name, { bytes, location: at });
 }
 
+/**
+ * The loading generation's list for a JSON section, `{ items: [...] }`, created on first use. For
+ * a built-in module, which is evaluated once, whose declarations come from each generation's code
+ * (`material()` in `bevy-ts/material`). The section's location is the first caller's.
+ */
+export function sectionItems(name) {
+  const g = loadingOrThrow(`sectionItems(${name})`);
+  let s = g.sections.get(name);
+  if (!s || !s.items) {
+    s = { items: [], location: callerLocation() };
+    g.sections.set(name, s);
+  }
+  return s.items;
+}
+
 /** Decodes UTF-8 bytes, for entries that take text or JSON payloads. */
 export function text(bytes) {
   return decoder.decode(bytes);
@@ -1093,7 +1108,7 @@ function end() {
     })),
     entries: g.entries,
   };
-  const sections = [...g.sections].map(([name, s]) => [name, s.bytes, s.location || null]);
+  const sections = [...g.sections].map(([name, s]) => [name, s.items ? encoder.encode(JSON.stringify({ items: s.items })) : s.bytes, s.location || null]);
   return [JSON.stringify(manifest), sections];
 }
 

package/runtime/material.js

@@ -0,0 +1,101 @@
+// @generated from crates/bevy-ts-material/ts/material.js by scripts/sync-runtime.mjs. Do not edit.
+// `bevy-ts/material`: script materials. A material is a name, a params schema in WGSL types and
+// `.wgsl` files imported like modules; Rust lays out the params, generates their declarations and
+// draws it with one erased material. Served by the engine; evaluated once, so each declaration
+// goes into the loading generation's `materials` section.
+import { sectionItems } from "bevy-ts";
+
+export const f32 = "f32";
+export const i32 = "i32";
+export const u32 = "u32";
+export const vec2f = "vec2f";
+export const vec3f = "vec3f";
+export const vec4f = "vec4f";
+export const mat4x4f = "mat4x4f";
+/** A `vec4<f32>` in linear RGBA, written as `"#f80"` or sRGB `[r, g, b, a?]`. */
+export const color = "color";
+/** A 2D texture with a filtering sampler, `<name>` and `<name>_sampler` in WGSL. */
+export const texture2d = "texture2d";
+
+const BASES = new Set([f32, i32, u32, vec2f, vec3f, vec4f, mat4x4f, color]);
+const ALPHA = new Set(["opaque", "blend", "premultiplied", "add", "multiply", "alphaToCoverage"]);
+
+/** A fixed array, strided to 16 bytes; scalar and `vec2f` elements read as `.x`/`.xy` of a `vec4`. */
+export function array(of, len) {
+  if (!BASES.has(of)) throw new Error(`array(${JSON.stringify(of)}, ${len}): elements are f32, i32, u32, vec2f, vec3f, vec4f, mat4x4f or color`);
+  if (!Number.isInteger(len) || len < 1) throw new Error(`array(${of}, ${len}): the length is a positive integer`);
+  return Object.freeze({ array: of, len });
+}
+
+const FRAME = /\(?((?:file|bevy-ts):[^\s()]+?):(\d+):(\d+)\)?\s*$/;
+
+function callerLocation() {
+  for (const line of String(new Error().stack).split("\n").slice(1)) {
+    if (/bevy-ts:/.test(line)) continue;
+    const m = FRAME.exec(line);
+    if (m) return { file: m[1].replace(/\?gen=\d+$/, ""), line: +m[2], column: +m[3] };
+  }
+  return undefined;
+}
+
+function located(message, location) {
+  const e = new Error(message);
+  e.bevyTsLocation = location;
+  return e;
+}
+
+function isShaderFile(v) {
+  return v !== null && typeof v === "object" && v.kind === "shaderFile" && typeof v.path === "string";
+}
+
+/** A material kind: what `<material kind={...} />` names. Only `name` crosses into a scene. */
+class MaterialKind {
+  constructor(name) {
+    this.name = name;
+    Object.freeze(this);
+  }
+}
+
+/**
+ * `material("game::Glow", { params: { color: color, pulse: f32 }, fragment: glow })`, where
+ * `glow` is `import glow from "./glow.wgsl"`.
+ */
+export function material(name, decl) {
+  const at = callerLocation();
+  const fail = (m) => {
+    throw located(`material ${name}: ${m}`, at);
+  };
+  if (typeof name !== "string" || !name) throw located("material(name, ...): the name is a string (\"game::Glow\")", at);
+  if (!decl || typeof decl !== "object") fail("takes { params, fragment }");
+  for (const k of Object.keys(decl)) {
+    if (!["params", "textures", "fragment", "vertex", "alphaMode"].includes(k)) fail(`unknown option ${k}`);
+  }
+  const shader = (k) => {
+    const v = decl[k];
+    if (v === undefined) return null;
+    if (typeof v === "string") fail(`${k} is a WGSL file, import it: import shader from "./${k}.wgsl"; then ${k}: shader`);
+    if (!isShaderFile(v)) fail(`${k} is a shader file from a .wgsl import`);
+    return v.path;
+  };
+  const fragment = shader("fragment");
+  if (fragment === null) fail("needs a fragment shader");
+  const params = [];
+  for (const [p, type] of Object.entries(decl.params || {})) {
+    const ok = BASES.has(type) || (type && typeof type === "object" && BASES.has(type.array) && Number.isInteger(type.len));
+    if (!ok) fail(`param ${p} has type ${JSON.stringify(type)}; use f32, i32, u32, vec2f, vec3f, vec4f, mat4x4f, color or array(...)`);
+    params.push({ name: p, type });
+  }
+  const textures = [];
+  for (const [t, type] of Object.entries(decl.textures || {})) {
+    if (type !== texture2d) fail(`texture ${t} has type ${JSON.stringify(type)}; use texture2d`);
+    if (params.some((p) => p.name === t)) fail(`${t} is both a param and a texture`);
+    textures.push(t);
+  }
+  let alphaMode = decl.alphaMode === undefined ? "opaque" : decl.alphaMode;
+  if (typeof alphaMode === "object" && alphaMode !== null && typeof alphaMode.mask === "number") alphaMode = { mask: alphaMode.mask };
+  else if (!ALPHA.has(alphaMode)) fail(`alphaMode ${JSON.stringify(alphaMode)}; use ${[...ALPHA].join(", ")} or { mask: 0.5 }`);
+  const items = sectionItems("materials");
+  if (items.some((m) => m.name === name)) fail("is declared twice");
+  items.push({ name, params, textures, fragment, vertex: shader("vertex"), alphaMode, location: at || null });
+  return new MaterialKind(name);
+}

package/wgsl.d.ts

@@ -0,0 +1,6 @@
+// A `.wgsl` import is a shader file, for `material()` in `bevy-ts/material`. The engine resolves
+// it relative to the importing file and watches it; its WGSL never runs as JS.
+declare module "*.wgsl" {
+  const shader: { readonly kind: "shaderFile"; readonly path: string };
+  export default shader;
+}