pelican-engine 0.0.0-stage → 0.3.1

package/lib/sdk/index.js

@@ -0,0 +1,82 @@
+/** Pelican Engine public API. No renderer or GPU implementation types escape this module. */
+export const SDK_VERSION = "0.3.1";
+export const SYSTEM_PHASES = [
+    "input",
+    "prePhysics",
+    "physics",
+    "postPhysics",
+    "update",
+    "presentation",
+];
+export const GRAPH_TYPES = ["float", "vec2", "vec3", "vec4", "bool"];
+export const GRAPH_INPUT_TYPES = {
+    uv: "vec2", uv1: "vec2", positionWorld: "vec3", normalWorld: "vec3",
+    viewDirectionWorld: "vec3", vertexColor: "vec4", index: "float",
+    screenSize: "vec2", texelSize: "vec2",
+    pixelCoord: "vec2", outputSize: "vec2",
+    positionLocal: "vec3", normalLocal: "vec3", vertexIndex: "float", instanceIndex: "float",
+};
+export const GRAPH_OPERATIONS = {
+    unary: ["sin", "cos", "abs", "floor", "ceil", "fract", "negate", "saturate", "normalize", "length", "safeSqrt"],
+    binary: ["add", "subtract", "multiply", "safeDivide", "min", "max", "dot", "cross", "step", "lessThan", "lessEqual", "greaterThan", "greaterEqual", "equal", "and", "or"],
+    ternary: ["mix", "clamp", "smoothstep", "select"],
+};
+export function defineComponent(input) {
+    return { ...input, kind: "component" };
+}
+export function defineMaterial(input) {
+    return { ...input, kind: "material" };
+}
+export function definePostProcess(input) {
+    return { ...input, kind: "postprocess" };
+}
+export function defineCompute(input) {
+    return { ...input, kind: "compute" };
+}
+export function defineAsset(input) {
+    return { ...input, kind: "asset" };
+}
+export function definePrefab(input) {
+    return { ...input, kind: "prefab" };
+}
+export function defineScene(input) {
+    return { ...input, kind: "scene" };
+}
+export function defineSystem(input) {
+    return { ...input, kind: "system" };
+}
+export function defineGame(input) {
+    return { ...input, kind: "game" };
+}
+/** Runtime wrapper used by compiled game.js. Source declarations are never imported by the compiler. */
+export function instantiateGame(game, engine) {
+    let disposed = false;
+    const systems = [...(game.systems ?? [])];
+    engine.configureGameSystems?.(systems);
+    return {
+        update(dt) {
+            if (disposed)
+                throw new Error("TC_RUNTIME_DISPOSED: Game has been disposed.");
+            if (!Number.isFinite(dt) || dt < 0)
+                throw new Error("TC_RUNTIME_DT: Expected a finite, non-negative timestep.");
+            if (engine.runGameSystems)
+                engine.runGameSystems(systems, dt);
+            else {
+                // Compatibility for the M0 facade harness; the M1 browser host always owns scheduling.
+                const context = new Proxy(engine, {
+                    get(target, key, receiver) {
+                        if (["time", "entities", "random", "emit", "events"].includes(String(key)))
+                            throw new Error(`TC_RUNTIME_SERVICE_UNAVAILABLE: ${String(key)} requires a pelican runtime host.`);
+                        return Reflect.get(target, key, receiver);
+                    },
+                });
+                for (const system of systems)
+                    system.run(context, dt);
+            }
+        },
+        dispose() {
+            disposed = true;
+            systems.length = 0;
+        },
+    };
+}

package/lib/tools/api-index.js

@@ -0,0 +1,113 @@
+import ts from "typescript";
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { SDK_VERSION } from "../sdk/index.js";
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+export function queryApiSymbol(symbols, args) {
+    const positions = args.flatMap((arg, i) => arg === "--symbol" ? [i] : []);
+    if (positions.length === 0)
+        return undefined;
+    if (positions.length !== 1)
+        throw new Error("TC_API_SYMBOL_DUPLICATE: Supply --symbol exactly once.");
+    const name = args[positions[0] + 1];
+    if (!name || name.startsWith("--"))
+        throw new Error("TC_API_SYMBOL_REQUIRED: Supply a public symbol name after --symbol.");
+    const matches = symbols.filter((symbol) => symbol.name === name);
+    if (matches.length === 0)
+        throw new Error("TC_API_SYMBOL_UNKNOWN: Symbol not found; use pelican api to inspect the public index and check exact spelling and case.");
+    return matches;
+}
+/** Public SDK source is the sole signature source; this file does not maintain duplicate API declarations. */
+export async function generateApiIndex(engineRoot = root) {
+    const filename = path.join(engineRoot, "packages/sdk/src/index.ts");
+    const source = await readFile(filename, "utf8");
+    const sf = ts.createSourceFile(filename, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+    const symbols = [];
+    for (const statement of sf.statements) {
+        if (!ts.canHaveModifiers(statement) ||
+            !ts
+                .getModifiers(statement)
+                ?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword))
+            continue;
+        const location = sf.getLineAndCharacterOfPosition(statement.getStart());
+        if (ts.isVariableStatement(statement)) {
+            for (const declaration of statement.declarationList.declarations)
+                symbols.push({
+                    name: declaration.name.getText(sf),
+                    kind: "constant",
+                    signature: declaration.getText(sf),
+                    line: location.line + 1,
+                });
+        }
+        else if (ts.isInterfaceDeclaration(statement) ||
+            ts.isTypeAliasDeclaration(statement) ||
+            ts.isFunctionDeclaration(statement)) {
+            const name = statement.name?.text;
+            if (!name)
+                continue;
+            const signature = ts.isFunctionDeclaration(statement) && statement.body
+                ? statement
+                    .getText(sf)
+                    .slice(0, statement.body.getStart() - statement.getStart())
+                    .trim() + ";"
+                : statement.getText(sf);
+            symbols.push({
+                name,
+                kind: ts.SyntaxKind[statement.kind],
+                signature,
+                line: location.line + 1,
+                ...(ts.isInterfaceDeclaration(statement)
+                    ? {
+                        fields: statement.members
+                            .map((m) => m.name?.getText(sf))
+                            .filter((v) => !!v),
+                    }
+                    : {}),
+            });
+        }
+    }
+    const index = {
+        format: "pelican.api-index",
+        version: 1,
+        engineVersion: SDK_VERSION,
+        entry: "pelican-engine",
+        source: "packages/sdk/src/index.ts",
+        symbols,
+    };
+    const output = path.join(engineRoot, "docs/api");
+    await mkdir(output, { recursive: true });
+    await writeFile(path.join(output, "index.json"), JSON.stringify(index, null, 2) + "\n");
+    const reference = [
+        `# pelican ${SDK_VERSION} API 索引`,
+        "",
+        "由公开 SDK 源码生成。签名以源码和 TypeScript 检查为准，不在文档维护第二套声明。",
+        "",
+        ...symbols.flatMap((symbol) => [
+            `## ${symbol.name}`,
+            "",
+            `来源：\`${index.source}:${symbol.line}\``,
+            "",
+            "```ts",
+            symbol.signature,
+            "```",
+            "",
+        ]),
+    ].join("\n");
+    await writeFile(path.join(output, "REFERENCE.md"), reference);
+    return index;
+}
+if (process.argv[1] &&
+    path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+    generateApiIndex()
+        .then((index) => console.log(JSON.stringify({
+        status: "succeeded",
+        engineVersion: SDK_VERSION,
+        symbols: index.symbols.length,
+        artifacts: ["docs/api/index.json", "docs/api/REFERENCE.md"],
+    })))
+        .catch((error) => {
+        console.error(String(error));
+        process.exitCode = 1;
+    });
+}

package/lib/tools/browser-session.js

@@ -0,0 +1,89 @@
+export class AutomationError extends Error {
+    code;
+    constructor(code, message, options) {
+        super(`${code}: ${message}`, options);
+        this.code = code;
+        this.name = "AutomationError";
+    }
+}
+function timeoutValue(timeoutMs) {
+    if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 120_000)
+        throw new AutomationError("TC_AUTOMATION_TIMEOUT_RANGE", "timeoutMs must be an integer in [1,120000].");
+    return timeoutMs;
+}
+export function automationLaunchOptions(timeoutMs = 30_000) {
+    return {
+        headless: false,
+        timeout: timeoutValue(timeoutMs),
+        args: [
+            "--use-angle=d3d11",
+            "--disable-background-timer-throttling",
+            "--disable-renderer-backgrounding",
+            "--disable-backgrounding-occluded-windows",
+            "--disable-features=CalculateNativeWinOcclusion",
+        ],
+    };
+}
+export function automationURL(url) {
+    const target = new URL(url);
+    target.searchParams.set("automation", "1");
+    return target.href;
+}
+/** The caller owns cleanup; a frozen renderer must not control the Node deadline. */
+export async function withAutomationDeadline(operation, timeoutMs = 30_000, label = "Browser operation") {
+    timeoutValue(timeoutMs);
+    let timer;
+    try {
+        return await Promise.race([
+            Promise.resolve().then(operation),
+            new Promise((_, reject) => {
+                timer = setTimeout(() => reject(new AutomationError("TC_AUTOMATION_TIMEOUT", `${label} exceeded its ${timeoutMs} ms Node deadline.`)), timeoutMs);
+            }),
+        ]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** No RAF polling: Chromium can suspend animation frames in occluded windows. */
+export async function waitForEngine(page, timeoutMs = 30_000, options = {}) {
+    timeoutValue(timeoutMs);
+    try {
+        await withAutomationDeadline(async () => {
+            const handle = await page.waitForFunction(({ production }) => {
+                const data = document.documentElement.dataset;
+                const runtime = globalThis;
+                const failure = runtime.__pelicanFailure || data.pelicanFailure;
+                if (failure)
+                    return { state: "failed", detail: String(failure) };
+                if (data.pelicanReady !== "true")
+                    return false;
+                if (!production &&
+                    typeof runtime.__pelican?.command !== "function")
+                    return false;
+                return { state: "ready" };
+            }, { production: options.production === true }, { polling: 100, timeout: timeoutMs });
+            try {
+                const status = await handle.jsonValue();
+                if (!status || typeof status !== "object" || !("state" in status))
+                    throw new AutomationError("TC_AUTOMATION_READY_PROTOCOL", "The readiness probe returned an invalid result.");
+                if (status.state === "failed")
+                    throw new AutomationError("TC_AUTOMATION_BOOT_FAILED", "detail" in status
+                        ? String(status.detail)
+                        : "Engine boot failed.");
+                if (status.state !== "ready")
+                    throw new AutomationError("TC_AUTOMATION_READY_PROTOCOL", "The readiness probe returned an unknown state.");
+            }
+            finally {
+                await handle.dispose();
+            }
+        }, timeoutMs, "Engine readiness");
+    }
+    catch (error) {
+        if (error instanceof AutomationError)
+            throw error;
+        throw new AutomationError(error instanceof Error && error.name === "TimeoutError"
+            ? "TC_AUTOMATION_TIMEOUT"
+            : "TC_AUTOMATION_WAIT_FAILED", "Engine readiness failed; close the owned browser before retrying.", { cause: error });
+    }
+}