@silkweaver/build 1.1.0 → 1.3.0

package/dist/build.d.ts

@@ -15,6 +15,16 @@ import type { project_file as project_data } from '@silkweaver/project';
 export type { project_data };
 /** Reads and parses a project's project.json. */
 export declare function read_project(project_folder: string): Promise<project_data>;
+/** Public: the engine version this toolchain ships — what "Update engine" would pin a project to. */
+export declare function toolchain_engine_version(): string;
+/**
+ * Vendors the toolchain's current engine into a project as one self-contained bundle
+ * (`.engine/engine.mjs`, matter-js inlined) and records its version (`.engine/version.json` +
+ * project.json `engineVersion`). Called at project creation; safe to re-run to upgrade the pin.
+ * @param project_folder - Absolute path to the project folder
+ * @returns The vendored engine version.
+ */
+export declare function vendor_engine(project_folder: string): Promise<string>;
 /**
  * Builds the game to a single bundled game.js at out_path, for the in-IDE preview.
  * @param out_path - Where to write game.js (the caller decides — e.g. exports/game.js)

package/dist/build.js

@@ -47,6 +47,8 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.read_project = read_project;
+exports.toolchain_engine_version = toolchain_engine_version;
+exports.vendor_engine = vendor_engine;
 exports.build_preview = build_preview;
 exports.export_html5 = export_html5;
 exports.export_executable = export_executable;
@@ -65,18 +67,73 @@ async function read_project(project_folder) {
  * entry can import the whole API (keeping it in sync with the IDE's autocomplete).
  * esbuild tree-shakes whatever the game doesn't actually use.
  */
-let _engine_names = null;
+const _engine_names = new Map(); // engine path → its export names (per vendored engine)
 async function engine_export_names(engine_path) {
-    if (_engine_names)
-        return _engine_names;
+    const cached = _engine_names.get(engine_path);
+    if (cached)
+        return cached;
     const mod = await import((0, node_url_1.pathToFileURL)(engine_path).href);
-    _engine_names = Object.keys(mod).filter(n => n !== 'default' && /^[A-Za-z_$][\w$]*$/.test(n));
-    return _engine_names;
+    const names = Object.keys(mod).filter(n => n !== 'default' && /^[A-Za-z_$][\w$]*$/.test(n));
+    _engine_names.set(engine_path, names);
+    return names;
 }
-/** Absolute path to the engine package entry — the esbuild alias target + export-name source. */
+/** Absolute path to the toolchain's own engine entry (the vendoring source + pre-vendoring fallback). */
 function engine_entry() {
     return require.resolve('@silkweaver/engine');
 }
+/** The version of the toolchain's own engine (what a freshly-vendored project pins). */
+function engine_version() {
+    try {
+        return JSON.parse(fs.readFileSync(path.join(path.dirname(engine_entry()), '..', 'package.json'), 'utf8')).version;
+    }
+    catch {
+        return '0.0.0';
+    }
+}
+/** Public: the engine version this toolchain ships — what "Update engine" would pin a project to. */
+function toolchain_engine_version() {
+    return engine_version();
+}
+/**
+ * Resolves the engine a project builds against: its vendored copy (`.engine/engine.mjs`) when
+ * present, else the toolchain's own engine (projects created before per-project vendoring). This is
+ * what lets a project keep building against the exact engine it was made with — IDE updates don't
+ * touch it.
+ */
+function resolve_engine(project_folder) {
+    const vendored = path.join(project_folder, '.engine', 'engine.mjs');
+    return fs.existsSync(vendored) ? vendored : engine_entry();
+}
+/**
+ * Vendors the toolchain's current engine into a project as one self-contained bundle
+ * (`.engine/engine.mjs`, matter-js inlined) and records its version (`.engine/version.json` +
+ * project.json `engineVersion`). Called at project creation; safe to re-run to upgrade the pin.
+ * @param project_folder - Absolute path to the project folder
+ * @returns The vendored engine version.
+ */
+async function vendor_engine(project_folder) {
+    const version = engine_version();
+    const dir = path.join(project_folder, '.engine');
+    await fs.promises.mkdir(dir, { recursive: true });
+    const esbuild_api = require('esbuild');
+    await esbuild_api.build({
+        entryPoints: [engine_entry()],
+        bundle: true,
+        format: 'esm',
+        outfile: path.join(dir, 'engine.mjs'),
+        keepNames: true, // the engine reads constructor.name at runtime
+    });
+    await fs.promises.writeFile(path.join(dir, 'version.json'), JSON.stringify({ version, vendoredAt: new Date().toISOString() }, null, 2) + '\n', 'utf8');
+    // Pin the version in project.json so the IDE can display it / gate features on it.
+    try {
+        const proj_path = path.join(project_folder, 'project.json');
+        const proj = JSON.parse(await fs.promises.readFile(proj_path, 'utf8'));
+        proj.engineVersion = version;
+        await fs.promises.writeFile(proj_path, JSON.stringify(proj, null, 2) + '\n', 'utf8');
+    }
+    catch { /* no project.json yet — caller sets engineVersion */ }
+    return version;
+}
 /**
  * Strips leading `import …` lines from a code snippet so it can be inlined inside a
  * function body (timeline moments). Engine references auto-resolve via the inject shim,
@@ -101,7 +158,7 @@ function hex_to_bgr(hex) {
  * Generates the bootstrapper (_entry.ts) source for a project.
  * @param asset_mode - 'preview' (file:// into project) or 'export' (relative assets/)
  */
-async function generate_entry_code(project_folder, proj, asset_mode) {
+async function generate_entry_code(project_folder, proj, asset_mode, engine_path) {
     // Parent-before-child so generated imports/registrations init objects in dependency order.
     const object_names = await _objects_parent_first(project_folder, Object.keys(proj.resources.objects ?? {}));
     const room_names = Object.keys(proj.resources.rooms ?? {});
@@ -110,8 +167,7 @@ async function generate_entry_code(project_folder, proj, asset_mode) {
     const font_names = Object.keys(proj.resources.fonts ?? {});
     const path_names = Object.keys(proj.resources.paths ?? {});
     const timeline_names = Object.keys(proj.resources.timelines ?? {});
-    // The engine is resolved from the @silkweaver/engine package (no path coupling).
-    const engine_path = engine_entry();
+    // engine_path is whatever the project resolves to — its vendored copy, or the toolchain's.
     // Each object is a single class file: objects/<name>.ts (a gm_object subclass).
     // It is imported as-is; metadata/variables/events all live in the class.
     const object_imports = [];
@@ -492,7 +548,8 @@ ${room_physics[start_room] ? `    physics_world_create(${room_physics[start_room
  * ESM game.js at out_path via esbuild, then removes the temporary file.
  */
 async function bundle_game(project_folder, proj, asset_mode, out_path, minify) {
-    const entry_code = await generate_entry_code(project_folder, proj, asset_mode);
+    const engine_path = resolve_engine(project_folder);
+    const entry_code = await generate_entry_code(project_folder, proj, asset_mode, engine_path);
     const entry_path = path.join(project_folder, '_entry.ts');
     const globals_path = path.join(project_folder, '_engine_globals.ts');
     await fs.promises.writeFile(entry_path, entry_code, 'utf8');
@@ -500,7 +557,7 @@ async function bundle_game(project_folder, proj, asset_mode, out_path, minify) {
     // `inject`, it makes any *bare* engine reference in an object/script file (e.g. `gm_object`,
     // `draw_sprite`) resolve to an auto-injected import — tree-shaken — so users never write or
     // manage `import … from '@silkweaver/engine'` themselves.
-    const engine_names = await engine_export_names(engine_entry());
+    const engine_names = await engine_export_names(engine_path);
     // Also re-export the project's OBJECT classes by name, so they can be referenced bare —
     // GMS-style, e.g. `place_meeting(x, y, obj_wall)` or `static parent = par_solid` — with no
     // import (matching what the IDE editor already declares). The defining file won't self-import;
@@ -533,7 +590,7 @@ async function bundle_game(project_folder, proj, asset_mode, out_path, minify) {
             // `this.constructor.name` (resource.name, room type checks, object_get_name),
             // so identifier mangling would otherwise break exported (minified) games.
             keepNames: true,
-            alias: { '@silkweaver/engine': engine_entry() },
+            alias: { '@silkweaver/engine': engine_path },
             inject: [globals_path],
         });
     }

package/dist/object_format.d.ts

@@ -10,7 +10,9 @@
  * Pure Node (typescript only) — unit-testable and reusable outside the IPC layer.
  */
 /** Known static-metadata field names an object class may declare. */
-export type meta_field = 'sprite' | 'solid' | 'visible' | 'persistent' | 'depth' | 'parent';
+export type meta_field = 'sprite' | 'solid' | 'visible' | 'persistent' | 'depth' | 'parent' | 'physics' | 'physics_shape' | 'physics_density' | 'physics_restitution' | 'physics_friction' | 'physics_sensor';
+/** Canonical order of the `static` metadata fields (keeps them tidy + consistent across files). */
+export declare const META_ORDER: string[];
 /** Canonical GMS-style order of `on_*` event methods (used to keep events ordered in code). */
 export declare const EVENT_ORDER: string[];
 export interface object_model {
@@ -26,6 +28,7 @@ export interface object_model {
         value: string;
     }[];
     events: string[];
+    statics: Record<string, string>;
 }
 /** Extracts the object model from a class-file source. */
 export declare function parse_object(src: string): object_model;
@@ -68,9 +71,15 @@ export declare function get_event_body(src: string, method: string): string | nu
  */
 export declare function set_event_body(src: string, method: string, body: string): string;
 /**
- * Normalizes a class-per-object file for display in the full code view: variables hoisted above all
- * events, canonical event order, then consistent indentation. Unchanged if there's no class.
+ * Normalizes a class-per-object file for the full code view: metadata → variables → events
+ * (execution order), a `;` on every field, then consistent indentation. The IDE only applies this
+ * when the user's "auto-organize objects" setting is on. Unchanged if there's no class.
  */
 export declare function normalize_object(src: string): string;
-/** Generates a minimal class-file source for a new object. Imports are auto-managed (none needed). */
-export declare function scaffold_object(class_name: string): string;
+/**
+ * Generates a class-file source for a new object. `kind` picks a starting template:
+ *   - 'normal'  → an empty object with an on_create stub;
+ *   - 'physics' → a ready-to-run dynamic matter.js body (physics metadata + a body-sizing mask).
+ * Imports are auto-managed (none needed).
+ */
+export declare function scaffold_object(class_name: string, kind?: 'normal' | 'physics'): string;

package/dist/object_format.js

@@ -44,7 +44,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.EVENT_ORDER = void 0;
+exports.EVENT_ORDER = exports.META_ORDER = void 0;
 exports.parse_object = parse_object;
 exports.this_members = this_members;
 exports.set_static = set_static;
@@ -58,6 +58,11 @@ exports.set_event_body = set_event_body;
 exports.normalize_object = normalize_object;
 exports.scaffold_object = scaffold_object;
 const ts = __importStar(require("typescript"));
+/** Canonical order of the `static` metadata fields (keeps them tidy + consistent across files). */
+exports.META_ORDER = [
+    'sprite', 'parent', 'solid', 'visible', 'persistent', 'depth',
+    'physics', 'physics_shape', 'physics_density', 'physics_restitution', 'physics_friction', 'physics_sensor',
+];
 /** Canonical GMS-style order of `on_*` event methods (used to keep events ordered in code). */
 exports.EVENT_ORDER = [
     'on_create', 'on_destroy',
@@ -94,7 +99,7 @@ function parse_object(src) {
         class_name: cls?.name?.text ?? '',
         sprite: null, parent: null,
         solid: false, visible: true, persistent: false, depth: 0,
-        variables: [], events: [],
+        variables: [], events: [], statics: {},
     };
     if (!cls)
         return model;
@@ -111,6 +116,7 @@ function parse_object(src) {
                 continue;
             const init = m.initializer ? m.initializer.getText(sf) : '';
             if (_is_static(m)) {
+                model.statics[n] = init; // generic: every static field, by name
                 switch (n) {
                     case 'sprite':
                         model.sprite = _string_literal(m.initializer);
@@ -225,9 +231,24 @@ function set_static(src, name, expr) {
     }
     if (existing) {
         // declared without initializer — replace the whole member
-        return _apply(src, { start: existing.getStart(sf), end: existing.getEnd(), text: `static ${name} = ${expr}` });
+        return _apply(src, { start: existing.getStart(sf), end: existing.getEnd(), text: `static ${name} = ${expr};` });
     }
-    return _insert_member(src, `    static ${name} = ${expr}\n`);
+    // New static: metadata lives at the TOP, ordered by META_ORDER. Insert before the first static
+    // that sorts after it; else before the first non-static member (so statics stay grouped up top).
+    const stub = `    static ${name} = ${expr};\n`;
+    const order = exports.META_ORDER.indexOf(name);
+    if (order >= 0) {
+        const after = cls.members.find(m => {
+            const n = _name_of(m);
+            return ts.isPropertyDeclaration(m) && _is_static(m) && n != null && exports.META_ORDER.indexOf(n) > order;
+        });
+        if (after)
+            return _insert_before(src, after.getStart(sf), stub);
+    }
+    const first_non_static = cls.members.find(m => !(ts.isPropertyDeclaration(m) && _is_static(m)));
+    if (first_non_static)
+        return _insert_before(src, first_non_static.getStart(sf), stub);
+    return _insert_member(src, stub);
 }
 /** Removes a static metadata field if present (e.g. clearing the sprite). */
 function remove_static(src, name) {
@@ -244,15 +265,19 @@ function set_field(src, name, expr) {
         return _apply(src, { start: existing.initializer.getStart(sf), end: existing.initializer.getEnd(), text: expr });
     }
     if (existing) {
-        return _apply(src, { start: existing.getStart(sf), end: existing.getEnd(), text: `${name} = ${expr}` });
+        return _apply(src, { start: existing.getStart(sf), end: existing.getEnd(), text: `${name} = ${expr};` });
     }
-    // New variable: keep all instance variables grouped at the TOP of the class, in add-order, so
-    // every event below can reference them — and a later variable's initializer can safely read an
-    // earlier one. Insert after the last existing variable; if none, before the first member.
-    const stub = `    ${name} = ${expr}\n`;
-    const vars = cls.members.filter(m => ts.isPropertyDeclaration(m) && !_is_static(m));
+    // New variable: variables sit between the static metadata and the events, in add-order (so a later
+    // one can read an earlier one, and every event below can reference them). Insert after the last
+    // variable; else after the last static; else before the first member.
+    const stub = `    ${name} = ${expr};\n`;
+    const props = cls.members.filter(m => ts.isPropertyDeclaration(m));
+    const vars = props.filter(m => !_is_static(m));
+    const statics = props.filter(m => _is_static(m));
     if (vars.length)
         return _insert_after(src, vars[vars.length - 1].getEnd(), stub);
+    if (statics.length)
+        return _insert_after(src, statics[statics.length - 1].getEnd(), stub);
     if (cls.members.length)
         return _insert_before(src, cls.members[0].getStart(sf), stub);
     return _insert_member(src, stub);
@@ -463,12 +488,12 @@ function _reindent(code, unit = '    ') {
 }
 /**
  * Reorders all class members into canonical groups, preserving each member's attached comments:
- *   1. instance variables — in their existing relative order (field-init order can matter; one
+ *   1. `static` metadata (sprite/parent/solid/…) — at the TOP, in META_ORDER (non-meta statics after);
+ *   2. instance variables — in their existing relative order (field-init order can matter; one
  *      field's initializer may read another), so they're grouped but never shuffled among themselves;
- *   2. `on_*` event methods — in canonical EVENT_ORDER;
- *   3. everything else (statics, helper methods) — in place.
- * Variables-before-events is the whole point: every event can reference every variable. A no-op if
- * the order is already canonical.
+ *   3. `on_*` event methods — in canonical EVENT_ORDER;
+ *   4. everything else (helper methods) — in place, at the bottom.
+ * Metadata → variables → events (execution order) is the canonical shape. A no-op if already canonical.
  */
 function _reorder_members(src) {
     const sf = _source(src);
@@ -480,11 +505,19 @@ function _reorder_members(src) {
         const n = _name_of(m);
         return n && ts.isMethodDeclaration(m) ? exports.EVENT_ORDER.indexOf(n) : -1;
     };
+    const is_static_prop = (m) => ts.isPropertyDeclaration(m) && _is_static(m);
     const is_var = (m) => ts.isPropertyDeclaration(m) && !_is_static(m);
+    // Statics: META_ORDER fields first (sprite, parent, …); any other static keeps its relative place.
+    const static_key = (m) => {
+        const n = _name_of(m);
+        const i = n ? exports.META_ORDER.indexOf(n) : -1;
+        return i >= 0 ? i : exports.META_ORDER.length + members.indexOf(m);
+    };
+    const statics = members.filter(is_static_prop).sort((a, b) => static_key(a) - static_key(b));
     const vars = members.filter(is_var);
     const events = members.filter(m => event_idx(m) >= 0).sort((a, b) => event_idx(a) - event_idx(b));
-    const others = members.filter(m => !is_var(m) && event_idx(m) < 0);
-    const ordered = [...vars, ...events, ...others];
+    const rest = members.filter(m => !is_static_prop(m) && !is_var(m) && event_idx(m) < 0);
+    const ordered = [...statics, ...vars, ...events, ...rest];
     if (ordered.every((m, i) => m === members[i]))
         return src; // already canonical
     // Rebuild the class body from each member's full text (getFullStart → getEnd includes the leading
@@ -495,18 +528,56 @@ function _reorder_members(src) {
     const suffix = src.slice(members[members.length - 1].getEnd());
     return prefix + ordered.map(chunk).join('') + suffix;
 }
+/** Ensures every field declaration (static + instance) ends with a `;`. Methods are left as-is. */
+function _ensure_field_semicolons(src) {
+    const sf = _source(src);
+    const cls = _find_class(sf);
+    if (!cls)
+        return src;
+    const ends = [];
+    for (const m of cls.members) {
+        if (!ts.isPropertyDeclaration(m))
+            continue;
+        const end = m.getEnd();
+        if (src[end - 1] !== ';')
+            ends.push(end);
+    }
+    let out = src;
+    for (const pos of ends.sort((a, b) => b - a))
+        out = out.slice(0, pos) + ';' + out.slice(pos);
+    return out;
+}
 /**
- * Normalizes a class-per-object file for display in the full code view: variables hoisted above all
- * events, canonical event order, then consistent indentation. Unchanged if there's no class.
+ * Normalizes a class-per-object file for the full code view: metadata → variables → events
+ * (execution order), a `;` on every field, then consistent indentation. The IDE only applies this
+ * when the user's "auto-organize objects" setting is on. Unchanged if there's no class.
  */
 function normalize_object(src) {
-    return _reindent(_reorder_members(src));
+    return _reindent(_ensure_field_semicolons(_reorder_members(src)));
 }
 // =========================================================================
 // Scaffolding
 // =========================================================================
-/** Generates a minimal class-file source for a new object. Imports are auto-managed (none needed). */
-function scaffold_object(class_name) {
+/**
+ * Generates a class-file source for a new object. `kind` picks a starting template:
+ *   - 'normal'  → an empty object with an on_create stub;
+ *   - 'physics' → a ready-to-run dynamic matter.js body (physics metadata + a body-sizing mask).
+ * Imports are auto-managed (none needed).
+ */
+function scaffold_object(class_name, kind = 'normal') {
+    if (kind === 'physics') {
+        return `export class ${class_name} extends gm_object {
+    static physics = true;
+    static physics_shape = 'box';
+    static physics_density = 0.5;
+    static physics_restitution = 0.1;
+    static physics_friction = 0.2;
+    on_create(): void {
+        this.mask_set_size(32, 32);
+    }
+}
+`;
+    }
     return `export class ${class_name} extends gm_object {
     on_create(): void {
 

package/dist/templates.js

@@ -45,6 +45,7 @@ exports.list_templates = list_templates;
 exports.create_from_template = create_from_template;
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
+const build_js_1 = require("./build.js");
 /** Ordered registry of the bundled starter templates (folders live under ../templates/<id>). */
 const TEMPLATE_REGISTRY = [
     { id: 'empty', label: 'Empty', description: 'A blank project with a single empty room.' },
@@ -56,7 +57,7 @@ function templates_dir() {
     return path.join(__dirname, '..', 'templates');
 }
 /** Names never copied into a new project (build artifacts / VCS / deps), as a defensive guard. */
-const COPY_DENYLIST = new Set(['_entry.ts', '_engine_globals.ts', 'node_modules', '.git', 'exports', 'game.js']);
+const COPY_DENYLIST = new Set(['_entry.ts', '_engine_globals.ts', 'node_modules', '.git', 'exports', 'game.js', '.engine']);
 /** Returns the available starter templates — only those whose folder is actually installed. */
 function list_templates() {
     const out = [];
@@ -103,4 +104,11 @@ async function create_from_template(template_id, dest_folder, name) {
         }
         catch { /* keep the template's bundled name */ }
     }
+    // Vendor the current engine into the new project so it's pinned to this version (a later IDE
+    // update won't change it). Best-effort: if it fails, the project still builds against the
+    // toolchain engine via the resolve_engine fallback.
+    try {
+        await (0, build_js_1.vendor_engine)(dest_folder);
+    }
+    catch { /* falls back to the toolchain engine */ }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@silkweaver/build",
-    "version": "1.1.0",
+    "version": "1.3.0",
     "description": "Silkweaver toolchain — compiles a project folder into a runnable game (HTML5 / desktop executable). Usable from a CLI or the IDE.",
     "type": "commonjs",
     "license": "GPL-3.0",