@silkweaver/build 1.0.0 → 1.2.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;
@@ -54,6 +56,7 @@ const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
 const os = __importStar(require("node:os"));
 const node_url_1 = require("node:url");
+const object_format_js_1 = require("./object_format.js");
 /** Reads and parses a project's project.json. */
 async function read_project(project_folder) {
     const proj_text = await fs.promises.readFile(path.join(project_folder, 'project.json'), 'utf8');
@@ -64,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,
@@ -100,23 +158,25 @@ 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) {
-    const object_names = Object.keys(proj.resources.objects ?? {});
+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 ?? {});
     const sprite_names = Object.keys(proj.resources.sprites ?? {});
     const script_names = Object.keys(proj.resources.scripts ?? {});
     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 = [];
+    const object_registrations = []; // object_register_name('x', x) → resolves object_get('x')
     for (const obj_name of object_names) {
         const class_file = path.join(project_folder, 'objects', `${obj_name}.ts`);
         if (await _path_exists(class_file)) {
             object_imports.push(`import { ${obj_name} } from '${class_file.replace(/\\/g, '/')}'`);
+            object_registrations.push(`object_register_name('${obj_name}', ${obj_name})`);
         }
         else {
             console.warn(`[build] object '${obj_name}' has no objects/${obj_name}.ts — skipped`);
@@ -323,6 +383,9 @@ ${engine_import}
 
 ${object_imports.join('\n')}
 
+// Register objects by name so object_get('name') resolves them at runtime.
+${object_registrations.join('\n')}
+
 ${script_imports}
 
 // ── Sprite loader ───────────────────────────────────────────────────────────
@@ -485,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');
@@ -493,8 +557,24 @@ 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());
-    await fs.promises.writeFile(globals_path, `export { ${engine_names.join(', ')} } from '@silkweaver/engine'\n`, 'utf8');
+    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;
+    // skip any object whose name would collide with an engine export.
+    // Parent-before-child order: the re-export order here becomes the module init order, so an
+    // object's `static parent = par` resolves to a defined class instead of undefined.
+    const object_order = await _objects_parent_first(project_folder, Object.keys(proj.resources.objects ?? {}));
+    const object_lines = [];
+    for (const obj_name of object_order) {
+        if (engine_names.includes(obj_name))
+            continue;
+        const class_file = path.join(project_folder, 'objects', `${obj_name}.ts`);
+        if (await _path_exists(class_file)) {
+            object_lines.push(`export { ${obj_name} } from '${class_file.replace(/\\/g, '/')}'`);
+        }
+    }
+    await fs.promises.writeFile(globals_path, `export { ${engine_names.join(', ')} } from '@silkweaver/engine'\n${object_lines.join('\n')}\n`, 'utf8');
     try {
         // Run esbuild via its Node API. Alias the package specifier to the resolved engine
         // entry so the generated entry AND any class-per-object files resolve to the same
@@ -506,7 +586,11 @@ async function bundle_game(project_folder, proj, asset_mode, out_path, minify) {
             outfile: out_path,
             format: 'esm',
             minify,
-            alias: { '@silkweaver/engine': engine_entry() },
+            // Preserve class/function `.name` even when minifying — the engine reads
+            // `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_path },
             inject: [globals_path],
         });
     }
@@ -686,6 +770,48 @@ async function _path_exists(p) {
         return false;
     }
 }
+/**
+ * Orders object names so every object's `static parent` (when it's another project object)
+ * appears BEFORE it. esbuild lazy-initializes the object modules (the inject shim and each
+ * object form an import cycle), running them in declaration order inside one initializer; a
+ * child whose `static parent = par` is evaluated before `par`'s module would capture
+ * `undefined`. Initializing parents first makes the reference resolve to the real class.
+ * A parent cycle (user error) is broken gracefully so this never loops.
+ */
+async function _objects_parent_first(project_folder, names) {
+    const present = new Set(names);
+    const parent_of = new Map();
+    for (const name of names) {
+        const file = path.join(project_folder, 'objects', `${name}.ts`);
+        let parent;
+        if (await _path_exists(file)) {
+            try {
+                const p = (0, object_format_js_1.parse_object)(await fs.promises.readFile(file, 'utf8')).parent;
+                if (p && p !== name && present.has(p))
+                    parent = p;
+            }
+            catch { /* unparseable — treat as no parent */ }
+        }
+        parent_of.set(name, parent);
+    }
+    const out = [];
+    const done = new Set();
+    const onstack = new Set();
+    const visit = (n) => {
+        if (done.has(n) || onstack.has(n))
+            return; // onstack guard breaks any parent cycle
+        onstack.add(n);
+        const p = parent_of.get(n);
+        if (p)
+            visit(p);
+        onstack.delete(n);
+        done.add(n);
+        out.push(n);
+    };
+    for (const n of names)
+        visit(n);
+    return out;
+}
 /** Recursively copies a directory tree from src to dst. */
 async function _copy_dir(src, dst) {
     await fs.promises.mkdir(dst, { recursive: true });

package/dist/index.d.ts

@@ -7,7 +7,9 @@
  *   - export_executable  → a packaged desktop application
  *
  * Also re-exports the class-file object read/write layer (object_format) used by the
- * IDE's object editor. Pure Node — drives both the IDE (over IPC) and the CLI.
+ * IDE's object editor, and the starter-template materializer (templates). Pure Node —
+ * drives both the IDE (over IPC) and the CLI.
  */
 export * from './build.js';
 export * from './object_format.js';
+export * from './templates.js';

package/dist/index.js

@@ -8,7 +8,8 @@
  *   - export_executable  → a packaged desktop application
  *
  * Also re-exports the class-file object read/write layer (object_format) used by the
- * IDE's object editor. Pure Node — drives both the IDE (over IPC) and the CLI.
+ * IDE's object editor, and the starter-template materializer (templates). Pure Node —
+ * drives both the IDE (over IPC) and the CLI.
  */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
@@ -27,3 +28,4 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./build.js"), exports);
 __exportStar(require("./object_format.js"), exports);
+__exportStar(require("./templates.js"), exports);

package/dist/object_format.d.ts

@@ -11,6 +11,8 @@
  */
 /** Known static-metadata field names an object class may declare. */
 export type meta_field = 'sprite' | 'solid' | 'visible' | 'persistent' | 'depth' | 'parent';
+/** 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 {
     class_name: string;
     sprite: string | null;
@@ -27,6 +29,14 @@ export interface object_model {
 }
 /** Extracts the object model from a class-file source. */
 export declare function parse_object(src: string): object_model;
+/**
+ * Collects every instance member reachable through `this.` in a class: declared instance fields
+ * *plus* members created/assigned at runtime inside any event (e.g. `this.velocity = 0` in on_create,
+ * read in on_step). This drives `this.` autocomplete, so a variable made in one event surfaces in all
+ * the others — matching the usual split of constants on the object, runtime state in Create. Static
+ * fields and method/event names are excluded (engine members are merged in separately).
+ */
+export declare function this_members(src: string): string[];
 /**
  * Sets (adds or updates) a static metadata field. `expr` is the raw initializer
  * text (e.g. `'spr_player'`, `true`, `-5`, `obj_base`).
@@ -38,9 +48,29 @@ export declare function remove_static(src: string, name: meta_field): string;
 export declare function set_field(src: string, name: string, expr: string): string;
 /** Removes an instance variable field. */
 export declare function remove_field(src: string, name: string): string;
-/** Adds an `on_*` event method stub if it is not already present. */
+/**
+ * Adds an `on_*` event method stub if it is not already present, inserted in canonical event
+ * order (before the first existing event method that comes later in EVENT_ORDER).
+ */
 export declare function add_method(src: string, method: string, params?: string, body?: string): string;
 /** Removes an event method by name. */
 export declare function remove_method(src: string, method: string): string;
+/**
+ * Returns one event method's body as an editable, de-indented buffer, or null if absent/bodyless.
+ * @param method - The on_* method to extract (e.g. 'on_step')
+ */
+export declare function get_event_body(src: string, method: string): string | null;
+/**
+ * Replaces an event method's body with `body` (an edited, de-indented buffer), re-indenting it to
+ * the method's level. Returns the full updated source; a no-op if the method is absent.
+ * @param method - The on_* method to update
+ * @param body   - The new body (column-0 / de-indented, as edited)
+ */
+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.
+ */
+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;