pixifact 0.3.0 → 0.4.0

package/README.md

@@ -15,8 +15,12 @@ bun add pixifact pixi.js
 ```ts
 import { parseSceneTemplate } from 'pixifact/compiler';
 import { Group } from 'pixifact/runtime';
+import { prepareSceneClass, scene } from 'pixifact/scene';
+import { createWechatPixiApplication } from 'pixifact/platform/wechat';
 ```
 
+`pixifact/compiler` 只包含解析、校验和生成 API。游戏运行时使用 `pixifact/runtime`、`pixifact/scene` 和具体平台入口，不要从 compiler 入口导入 Scene decorator 或运行时加载 API。
+
 Compiler Scene 项目通常还会安装 CLI：
 
 ```bash
@@ -30,6 +34,16 @@ pixifact scene validate --all
 pixifact compile-scenes
 ```
 
+声明 `targets.wechat` 后，可校验和构建微信小游戏：
+
+```bash
+pixifact validate --target wechat
+pixifact build --target wechat
+pixifact dev --target wechat
+```
+
+完整配置见仓库文档 [微信小游戏构建](https://github.com/hxg2050/pixifact/blob/main/docs/zh/wechat-minigame.md)。
+
 ## Scene 工作流
 
 Pixifact 把项目相对 `.scene` 文件作为 source of truth。外部 Agent 直接编辑 `.scene` 源文件，然后运行校验和编译。

package/dist/compiler/compileScenes.d.ts

@@ -3,6 +3,7 @@ export interface CompileScenesOptions {
     sourceRoots?: string[];
     generatedDir?: string;
 }
+export declare const generatedSceneAssetsFileName = "scene-assets.generated.json";
 export declare class CompileSceneError extends Error {
     readonly scene: string;
     readonly source?: string | undefined;

package/dist/compiler/compileScenes.js

@@ -9,6 +9,7 @@ import { findMissingScenePartReferences } from './scenePartValidation.js';
 import { parseSceneTemplate } from './templateParser.js';
 import { compileSceneTemplateToTs } from './typescriptCompiler.js';
 import { parsePixifactProjectConfig, pixifactProjectConfigFileName, } from '../project/index.js';
+export const generatedSceneAssetsFileName = 'scene-assets.generated.json';
 export class CompileSceneError extends Error {
     scene;
     source;
@@ -65,6 +66,7 @@ export async function compileScenes(options) {
     }
     const projectRegistryImports = [];
     const builtinRegistryImports = [];
+    const projectAssets = new Set();
     for (const record of sceneRecords) {
         const { scenePath } = record;
         const template = templates.get(scenePath);
@@ -84,9 +86,12 @@ export async function compileScenes(options) {
             },
             sceneImports: sceneImportsFor(template, templates, projectRoot, generatedFileDir),
             sceneClassAliases: sceneClassAliasesFor(template),
+            sceneDependencies: [...collectSceneInstancePaths(template.children)].sort(),
             sceneInterfaces: sceneInterfacesFor(template, templates),
-            textureImports: textureImportsFor(template, projectRoot, generatedFileDir),
         });
+        if (record.kind === 'project') {
+            collectTemplateTextures(template, projectAssets);
+        }
         await mkdir(path.dirname(generatedFile), { recursive: true });
         await writeFile(generatedFile, code);
         if (record.kind === 'project') {
@@ -100,6 +105,7 @@ export async function compileScenes(options) {
         ...builtinRegistryImports,
         ...projectRegistryImports,
     ].join('\n')}\n`);
+    await writeFile(path.join(generatedDir, generatedSceneAssetsFileName), `${JSON.stringify([...projectAssets].sort(), null, 2)}\n`);
 }
 async function readProjectConfig(projectRoot) {
     const configPath = path.join(projectRoot, pixifactProjectConfigFileName);
@@ -294,17 +300,10 @@ function importSourceFor(sourcePath, generatedFileDir) {
     const source = path.relative(generatedFileDir, sourcePath).replaceAll(path.sep, '/').replace(/\.ts$/, '');
     return source.startsWith('.') ? source : `./${source}`;
 }
-function textureImportsFor(template, projectRoot, generatedFileDir) {
-    const textures = new Set();
+function collectTemplateTextures(template, textures) {
     for (const child of template.children) {
         collectTextureReferences(child, textures);
     }
-    return Object.fromEntries([...textures].map((texture) => {
-        const normalized = texture.replace(/^\.\/+/, '').replace(/^\/+/, '');
-        const assetPath = path.resolve(projectRoot, normalized);
-        const source = path.relative(generatedFileDir, assetPath).replaceAll(path.sep, '/');
-        return [texture, `${source.startsWith('.') ? source : `./${source}`}?url`];
-    }));
 }
 function collectSceneInstancePaths(nodes, scenePaths = new Set()) {
     for (const node of nodes) {

package/dist/compiler/index.d.ts

@@ -1,15 +1,11 @@
 export * from './commands/index.js';
 export * from './builtinScenes.js';
-export * from './decorators.js';
-export * from './eventRuntime.js';
 export * from './pixiNodeSchema.js';
 export * from './spec.js';
 export * from './scriptInterfaceExtractor.js';
-export * from './sceneRuntime.js';
 export * from './sceneAssetPair.js';
 export * from './scenePartValidation.js';
 export * from './sceneValidation.js';
-export * from './slotRuntime.js';
 export * from './templateParser.js';
 export * from './templateSerializer.js';
 export * from './typescriptCompiler.js';

package/dist/compiler/index.js

@@ -1,15 +1,11 @@
 export * from './commands/index.js';
 export * from './builtinScenes.js';
-export * from './decorators.js';
-export * from './eventRuntime.js';
 export * from './pixiNodeSchema.js';
 export * from './spec.js';
 export * from './scriptInterfaceExtractor.js';
-export * from './sceneRuntime.js';
 export * from './sceneAssetPair.js';
 export * from './scenePartValidation.js';
 export * from './sceneValidation.js';
-export * from './slotRuntime.js';
 export * from './templateParser.js';
 export * from './templateSerializer.js';
 export * from './typescriptCompiler.js';

package/dist/compiler/spec.d.ts

@@ -73,8 +73,8 @@ export interface CompileSceneTemplateOptions {
     scriptImport?: SceneTemplateScriptImport;
     sceneImports?: SceneTemplateScriptImport[];
     sceneClassAliases?: Record<string, string>;
+    sceneDependencies?: string[];
     sceneInterfaces?: Record<string, SceneTemplateInterface>;
-    textureImports?: Record<string, string>;
 }
 export interface SceneScriptInterface {
     scene: string;

package/dist/compiler/typescriptCompiler.js

@@ -1,4 +1,5 @@
 import { pixiSceneDisplayProps, pixiSceneGraphicsProps, pixiSceneLayoutProps, pixiSceneRectProps, pixiSceneSpriteLikeProps, pixiSceneTextStyleProps, pixiSceneTransformProps, } from './pixiNodeSchema.js';
+import { compilerSceneNodeLocator } from './commands/index.js';
 const transformProps = new Set(pixiSceneTransformProps);
 const layoutProps = new Set(pixiSceneLayoutProps);
 const pixiProps = new Set(pixiSceneDisplayProps);
@@ -37,16 +38,18 @@ class CompileContext {
         const functionName = this.options.functionName || `mount${this.template.name}Scene`;
         const actionsParameter = this.options.actionsParameter || 'actions';
         const partsType = this.#formatPartsType();
-        const textureLoads = this.#formatTextureLoads();
+        const texturePreparation = this.#formatTexturePreparation();
         this.#lines.push(`export function ${functionName}(root: Group${this.#hasEvents() ? `, ${actionsParameter}: Record<string, () => void> = {}` : ''}) {`);
+        this.#lines.push('  const __pixifactNodes: Record<string, Container> = {};');
         this.#lines.push('  const __pixifactSlots: Record<string, Container> = {};');
         this.#applyRootProps();
-        for (const child of this.template.children) {
-            this.#compileNode(child, 'root', actionsParameter);
+        for (const [index, child] of this.template.children.entries()) {
+            this.#compileNode(child, 'root', actionsParameter, String(index));
         }
         this.#lines.push('  return {');
         this.#lines.push('    root,');
         this.#lines.push(`    parts: { ${this.#parts.map((part) => part.id).join(', ')} },`);
+        this.#lines.push('    nodes: __pixifactNodes,');
         this.#lines.push('    slots: __pixifactSlots,');
         this.#lines.push('  };');
         this.#lines.push('}');
@@ -57,7 +60,10 @@ class CompileContext {
             }
             this.#lines.push('');
             this.#lines.push(`registerScene(${JSON.stringify(this.options.registrationPath)}, {`);
+            this.#lines.push(`  assets: ${JSON.stringify([...this.#textures.keys()])},`);
+            this.#lines.push(`  dependencies: ${JSON.stringify(this.options.sceneDependencies ?? [])},`);
             this.#lines.push(`  mount: ${functionName},`);
+            this.#lines.push(`  prepare: ${this.#prepareFunctionName()},`);
             this.#lines.push('});');
             if (this.options.scriptImport) {
                 this.#lines.push(`registerSceneClass(${this.options.scriptImport.localName}, ${JSON.stringify(this.options.registrationPath)});`);
@@ -66,7 +72,7 @@ class CompileContext {
         const imports = this.#formatImports();
         return [
             imports,
-            textureLoads,
+            texturePreparation,
             partsType,
             this.#lines.join('\n'),
         ].filter(Boolean).join('\n\n') + '\n';
@@ -79,9 +85,6 @@ class CompileContext {
             ])];
         const runtimeImports = [...new Set(['Group', ...[...this.#pixiRuntimeImports].sort()])];
         const lines = [`import { ${imports.join(', ')} } from 'pixi.js';`, `import { ${runtimeImports.join(', ')} } from 'pixifact/runtime';`];
-        for (const [texture, variable] of this.#textureImportEntries()) {
-            lines.push(`import ${variable} from ${JSON.stringify(this.options.textureImports?.[texture])};`);
-        }
         for (const sceneImport of this.options.sceneImports ?? []) {
             const classImport = sceneImport.exportName === sceneImport.localName
                 ? sceneImport.exportName
@@ -98,7 +101,7 @@ class CompileContext {
             lines.push(`import { ${this.options.scriptImport.exportName} as ${this.options.scriptImport.localName} } from ${JSON.stringify(this.options.scriptImport.source)};`);
         }
         if (this.#runtimeImports.size > 0) {
-            lines.push(`import { ${[...this.#runtimeImports].sort().join(', ')} } from 'pixifact/compiler';`);
+            lines.push(`import { ${[...this.#runtimeImports].sort().join(', ')} } from 'pixifact/scene';`);
         }
         return lines.join('\n');
     }
@@ -109,6 +112,7 @@ class CompileContext {
             lines.push(`    ${part.id}: ${part.type};`);
         }
         lines.push('  };');
+        lines.push('  nodes: Record<string, Container>;');
         lines.push('  slots: Record<string, Container>;');
         lines.push('};');
         return lines.join('\n');
@@ -174,16 +178,27 @@ class CompileContext {
             }
         }
     }
-    #formatTextureLoads() {
+    #formatTexturePreparation() {
         if (this.#textures.size === 0) {
-            return '';
+            return `export async function ${this.#prepareFunctionName()}() {}`;
         }
-        this.#pixiImports.add('Assets');
-        return [...this.#textures.entries()]
-            .map(([texture, variable]) => `const ${variable} = await Assets.load(${this.#textureLoadSource(texture)});`)
-            .join('\n');
-    }
-    #compileNode(node, parent, actionsParameter) {
+        this.#pixiImports.add('Texture');
+        this.#runtimeImports.add('loadSceneTexture');
+        const entries = [...this.#textures.entries()];
+        return [
+            ...entries.map(([, variable]) => `let ${variable}: Texture;`),
+            '',
+            `export async function ${this.#prepareFunctionName()}() {`,
+            `  [${entries.map(([, variable]) => variable).join(', ')}] = await Promise.all([`,
+            ...entries.map(([texture]) => `    loadSceneTexture(${JSON.stringify(texture)}),`),
+            '  ]);',
+            '}',
+        ].join('\n');
+    }
+    #prepareFunctionName() {
+        return `prepare${this.template.name}Scene`;
+    }
+    #compileNode(node, parent, actionsParameter, path) {
         if (node.kind === 'slotOutlet') {
             this.#runtimeImports.add('registerSlot');
             this.#lines.push(`  __pixifactSlots[${JSON.stringify(node.name)}] = ${parent};`);
@@ -191,24 +206,27 @@ class CompileContext {
             return;
         }
         if (node.kind === 'sceneInstance') {
-            this.#compileSceneInstance(node, parent, actionsParameter);
+            this.#compileSceneInstance(node, parent, actionsParameter, path);
             return;
         }
-        this.#compilePixiNode(node, parent, actionsParameter);
+        this.#compilePixiNode(node, parent, actionsParameter, path);
     }
-    #compilePixiNode(node, parent, actionsParameter) {
+    #compilePixiNode(node, parent, actionsParameter, path) {
         const variable = node.id || this.#anonymousName(node.type);
+        const locator = compilerSceneNodeLocator(node, path);
         this.#lines.push(`  const ${variable} = ${this.#constructPixiNode(node)};`);
         this.#applyNodeId(variable, node.id);
         this.#applyPixiProps(variable, node.props, false, undefined, node.type);
         this.#applyParentSorting(parent, node.props);
         this.#lines.push(`  ${parent}.addChild(${variable});`);
-        for (const child of node.children) {
-            this.#compileNode(child, variable, actionsParameter);
+        this.#lines.push(`  __pixifactNodes[${JSON.stringify(locator)}] = ${variable};`);
+        for (const [index, child] of node.children.entries()) {
+            this.#compileNode(child, variable, actionsParameter, `${locator}/${index}`);
         }
     }
-    #compileSceneInstance(node, parent, actionsParameter) {
+    #compileSceneInstance(node, parent, actionsParameter, path) {
         const variable = node.id || this.#anonymousName(node.type);
+        const locator = compilerSceneNodeLocator(node, path);
         const constructorName = this.#sceneConstructorName(node);
         this.#lines.push(`  const ${variable} = new ${constructorName}();`);
         this.#applyPixiProps(variable, node.props, true, node);
@@ -218,20 +236,22 @@ class CompileContext {
         }
         this.#applyParentSorting(parent, node.props);
         this.#lines.push(`  ${parent}.addChild(${variable});`);
+        this.#lines.push(`  __pixifactNodes[${JSON.stringify(locator)}] = ${variable};`);
         for (const [slot, children] of Object.entries(node.slots)) {
-            for (const child of children) {
-                const childVariable = this.#compileSlottedNode(child, variable, actionsParameter);
+            for (const [index, child] of children.entries()) {
+                const childVariable = this.#compileSlottedNode(child, variable, actionsParameter, `${locator}/slot:${slot}/${index}`);
                 this.#runtimeImports.add('mount');
                 this.#lines.push(`  mount(${variable}, ${childVariable}, ${JSON.stringify(slot)});`);
             }
         }
     }
-    #compileSlottedNode(node, slotTarget, actionsParameter) {
+    #compileSlottedNode(node, slotTarget, actionsParameter, path) {
         if (node.kind === 'slotOutlet') {
             throw new Error(`Cannot place <slot> inside ${slotTarget}.`);
         }
         if (node.kind === 'sceneInstance') {
             const variable = node.id || this.#anonymousName(node.type);
+            const locator = compilerSceneNodeLocator(node, path);
             const constructorName = this.#sceneConstructorName(node);
             this.#lines.push(`  const ${variable} = new ${constructorName}();`);
             this.#applyPixiProps(variable, node.props, true, node);
@@ -239,9 +259,10 @@ class CompileContext {
                 this.#runtimeImports.add('connectSceneEvent');
                 this.#lines.push(`  connectSceneEvent(${variable}.${name}, ${JSON.stringify(action)}, root, ${actionsParameter});`);
             }
+            this.#lines.push(`  __pixifactNodes[${JSON.stringify(locator)}] = ${variable};`);
             for (const [slot, children] of Object.entries(node.slots)) {
-                for (const child of children) {
-                    const childVariable = this.#compileSlottedNode(child, variable, actionsParameter);
+                for (const [index, child] of children.entries()) {
+                    const childVariable = this.#compileSlottedNode(child, variable, actionsParameter, `${locator}/slot:${slot}/${index}`);
                     this.#runtimeImports.add('mount');
                     this.#lines.push(`  mount(${variable}, ${childVariable}, ${JSON.stringify(slot)});`);
                 }
@@ -249,11 +270,13 @@ class CompileContext {
             return variable;
         }
         const variable = node.id || this.#anonymousName(node.type);
+        const locator = compilerSceneNodeLocator(node, path);
         this.#lines.push(`  const ${variable} = ${this.#constructPixiNode(node)};`);
         this.#applyNodeId(variable, node.id);
         this.#applyPixiProps(variable, node.props, false, undefined, node.type);
-        for (const child of node.children) {
-            this.#compileNode(child, variable, actionsParameter);
+        this.#lines.push(`  __pixifactNodes[${JSON.stringify(locator)}] = ${variable};`);
+        for (const [index, child] of node.children.entries()) {
+            this.#compileNode(child, variable, actionsParameter, `${locator}/${index}`);
         }
         return variable;
     }
@@ -578,20 +601,6 @@ class CompileContext {
         this.#textures.set(texture, variable);
         return variable;
     }
-    #textureImportEntries() {
-        return [...this.#textures.keys()]
-            .filter((texture) => this.options.textureImports?.[texture])
-            .map((texture, index) => [texture, `__pixifactTextureUrl${index + 1}`]);
-    }
-    #textureImportVariable(texture) {
-        const index = [...this.#textures.keys()]
-            .filter((key) => this.options.textureImports?.[key])
-            .indexOf(texture);
-        return index >= 0 ? `__pixifactTextureUrl${index + 1}` : undefined;
-    }
-    #textureLoadSource(texture) {
-        return this.#textureImportVariable(texture) ?? this.#value(texture);
-    }
     #textureValue(value) {
         return typeof value === 'string' ? this.#textureVariable(value) : this.#value(value);
     }

package/dist/compiler-node/vite.d.ts

@@ -4,5 +4,6 @@ export interface PixifactScenesPluginOptions {
 }
 export declare function pixifactScenesPlugin(options?: PixifactScenesPluginOptions): {
     name: string;
-    resolveId(id: string): string | undefined;
+    resolveId(id: string): "\0pixifact:scenes" | undefined;
+    load(id: string): Promise<string | undefined>;
 };

package/dist/compiler-node/vite.js

@@ -1,5 +1,7 @@
+import { readFile } from 'node:fs/promises';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { generatedSceneAssetsFileName } from '../compiler/compileScenes.js';
 function projectRootPath(projectRoot) {
     if (typeof projectRoot === 'string') {
         return projectRoot;
@@ -10,12 +12,37 @@ function projectRootPath(projectRoot) {
     return process.cwd();
 }
 export function pixifactScenesPlugin(options = {}) {
-    const generatedDir = path.resolve(projectRootPath(options.projectRoot), options.generatedDir ?? '.pixifact/generated');
+    const projectRoot = projectRootPath(options.projectRoot);
+    const generatedDir = path.resolve(projectRoot, options.generatedDir ?? '.pixifact/generated');
     const sceneRegistry = path.join(generatedDir, 'scenes.generated.ts');
+    const sceneAssets = path.join(generatedDir, generatedSceneAssetsFileName);
+    const virtualSceneRegistry = '\0pixifact:scenes';
     return {
         name: 'pixifact-scenes',
         resolveId(id) {
-            return id === 'pixifact:scenes' ? sceneRegistry : undefined;
+            return id === 'pixifact:scenes' ? virtualSceneRegistry : undefined;
+        },
+        async load(id) {
+            if (id !== virtualSceneRegistry) {
+                return undefined;
+            }
+            const assets = JSON.parse(await readFile(sceneAssets, 'utf8'));
+            const imports = assets.map((asset, index) => `import __pixifactAsset${index + 1} from ${JSON.stringify(viteFileImport(path.resolve(projectRoot, asset), '?url'))};`);
+            const manifest = Object.fromEntries(assets.map((asset, index) => [
+                asset,
+                { src: `__pixifactAsset${index + 1}` },
+            ]));
+            const manifestSource = JSON.stringify(manifest, null, 2)
+                .replace(/"src": "(__pixifactAsset\d+)"/g, '"src": $1');
+            return [
+                ...imports,
+                "import { configureSceneAssets } from 'pixifact/scene';",
+                `import ${JSON.stringify(viteFileImport(sceneRegistry))};`,
+                `configureSceneAssets(${manifestSource});`,
+            ].join('\n');
         },
     };
 }
+function viteFileImport(filePath, suffix = '') {
+    return `/@fs/${filePath.replaceAll(path.sep, '/')}${suffix}`;
+}