pixifact 0.6.1 → 0.8.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 youxia
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,58 +1,59 @@
 # Pixifact
 
-Pixifact 是基于 PixiJS v8 的 Scene / UI / 轻场景语义层，面向 AI 可直接编辑的 `.scene` 工作流。
-
-`pixifact` 包提供项目配置解析、runtime 节点、compiler API 和生成 Scene 的运行时支持。CLI 和项目脚手架分别由 `pixifact-cli`、`create-pixifact` 提供。
+Pixifact 是基于 PixiJS v8、面向 AI 可编辑 `.scene` 工作流的 Scene / UI / 轻场景语义层。
 
 ## 安装
 
 ```bash
 bun add pixifact pixi.js
+bun add -d pixifact-cli vite
 ```
 
-## 使用
+只在需要时安装小游戏平台包：
 
-```ts
-import { parseSceneTemplate } from 'pixifact/compiler';
-import { Group } from 'pixifact/runtime';
-import { prepareSceneClass, scene } from 'pixifact/scene';
-import { createWechatPixiApplication } from 'pixifact/platform/wechat';
+```bash
+bun add @pixifact/platform-wechat
+bun add @pixifact/platform-douyin
 ```
 
-`pixifact/compiler` 只包含解析、校验和生成 API。游戏运行时使用 `pixifact/runtime`、`pixifact/scene` 和具体平台入口，不要从 compiler 入口导入 Scene decorator 或运行时加载 API。
+## Vite
 
-Compiler Scene 项目通常还会安装 CLI：
+```ts
+import { defineConfig } from 'vite';
+import { pixifact } from 'pixifact/compiler-node';
 
-```bash
-bun add -d pixifact-cli
+export default defineConfig({ plugins: [pixifact()] });
 ```
 
-然后校验和编译 `.scene` 文件：
-
-```bash
-pixifact scene validate --all
-pixifact compile-scenes
-```
+Web、微信和抖音共享 `src/main.ts`。平台由当前 Vite mode env 中的 `VITE_PLATFORM=web|wechat|douyin` 选择；小游戏还需要 `VITE_APP_ID`。
 
-声明 `targets.wechat` 后，可校验和构建微信小游戏：
+```ts
+import 'pixifact:scenes';
+import { Assets } from 'pixi.js';
+import { createApplication } from 'pixifact:platform';
+import manifest from 'pixifact:assets';
 
-```bash
-pixifact validate --target wechat
-pixifact build --target wechat
-pixifact dev --target wechat
+const app = await createApplication();
+await Assets.init({ manifest });
 ```
 
-完整配置见仓库文档 [微信小游戏构建](https://github.com/hxg2050/pixifact/blob/main/docs/zh/wechat-minigame.md)。
+`createApplication()` 返回原生 PixiJS `Application`，不隐式初始化 Assets。Scene 纹理和业务 JSON、音频、字体、资源包都沿用 PixiJS `Assets.load()` / `Assets.loadBundle()`。
 
 ## Scene 工作流
 
-Pixifact 把项目相对 `.scene` 文件作为 source of truth。外部 Agent 直接编辑 `.scene` 源文件，然后运行校验和编译。
+```bash
+pixifact scene validate --all
+pixifact compile-scenes
+pixifact validate --mode production
+pixifact build --mode production
+```
 
-`.pixifact/generated/**` 等生成文件是构建产物，不要手写修改。
+项目相对 `.scene` 是 source of truth；不要编辑 `.pixifact/generated/**`。解析、校验和生成 API 位于 `pixifact/compiler`，Node/Vite 插件位于 `pixifact/compiler-node`，runtime 与 Scene API 分别位于 `pixifact/runtime` 和 `pixifact/scene`。
+
+微信和抖音构建配置见仓库文档：[微信小游戏](https://github.com/hxg2050/pixifact/blob/main/docs/zh/wechat-minigame.md)、[抖音小游戏](https://github.com/hxg2050/pixifact/blob/main/docs/zh/douyin-minigame.md)。
 
 ## 环境要求
 
 - Bun
 - PixiJS v8
-
-桌面编辑器不包含在 npm runtime 包中。
+- Vite 6 或更高版本

package/dist/client.d.ts

@@ -0,0 +1,23 @@
+declare module 'pixifact:platform' {
+    import type { Application, ApplicationOptions } from 'pixi.js';
+
+    export function createApplication(
+        options?: Partial<ApplicationOptions>,
+    ): Promise<Application>;
+}
+
+declare module 'pixifact:assets' {
+    import type { AssetsManifest } from 'pixi.js';
+
+    const manifest: AssetsManifest;
+    export default manifest;
+}
+
+interface ImportMetaEnv {
+    readonly VITE_APP_ID?: string;
+    readonly VITE_PLATFORM: 'web' | 'wechat' | 'douyin';
+}
+
+interface ImportMeta {
+    readonly env: ImportMetaEnv;
+}

package/dist/compiler/compileScenes.js

@@ -1,4 +1,5 @@
-import { access, mkdir, readdir, readFile, writeFile } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import { access, mkdir, readdir, readFile, rename, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { builtinSceneAssetIds, builtinSceneNameFromAssetId, isBuiltinSceneAssetId, } from './builtinScenes.js';
@@ -123,7 +124,7 @@ export async function compileScenes(options) {
             collectTemplateTextures(template, projectAssets);
         }
         await mkdir(path.dirname(generatedFile), { recursive: true });
-        await writeFile(generatedFile, code);
+        await writeGeneratedFile(generatedFile, code);
         if (record.kind === 'project') {
             projectRegistryImports.push(`import ${JSON.stringify(generatedSceneModuleImport(scenePath))};`);
         }
@@ -131,11 +132,19 @@ export async function compileScenes(options) {
             builtinRegistryImports.push(`import ${JSON.stringify(generatedSceneModuleImport(scenePath))};`);
         }
     }
-    await writeFile(path.join(generatedDir, 'scenes.generated.ts'), `${[
+    await writeGeneratedFile(path.join(generatedDir, 'scenes.generated.ts'), `${[
         ...builtinRegistryImports,
         ...projectRegistryImports,
     ].join('\n')}\n`);
-    await writeFile(path.join(generatedDir, generatedSceneAssetsFileName), `${JSON.stringify([...projectAssets].sort(), null, 2)}\n`);
+    await writeGeneratedFile(path.join(generatedDir, generatedSceneAssetsFileName), `${JSON.stringify([...projectAssets].sort(), null, 2)}\n`);
+}
+async function writeGeneratedFile(filePath, content) {
+    if (await exists(filePath) && await readFile(filePath, 'utf8') === content) {
+        return;
+    }
+    const temporaryPath = `${filePath}.${process.pid}.${randomUUID()}.tmp`;
+    await writeFile(temporaryPath, content);
+    await rename(temporaryPath, filePath);
 }
 async function readProjectConfig(projectRoot) {
     const configPath = path.join(projectRoot, pixifactProjectConfigFileName);

package/dist/compiler/typescriptCompiler.js

@@ -186,15 +186,15 @@ class CompileContext {
         if (this.#textures.size === 0) {
             return `export async function ${this.#prepareFunctionName()}() {}`;
         }
+        this.#pixiImports.add('Assets');
         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)}),`),
+            ...entries.map(([texture]) => `    Assets.load<Texture>(${JSON.stringify(texture)}),`),
             '  ]);',
             '}',
         ].join('\n');

package/dist/compiler-node/runtimeVite.js

@@ -9,8 +9,10 @@ const runtimeAnnounceEvent = 'pixifact:runtime:announce';
 const runtimeRequestEvent = 'pixifact:runtime:request';
 const runtimeResponseEvent = 'pixifact:runtime:response';
 const runtimeApiRoot = '/__pixifact_runtime__';
+const runtimeScreenshotPath = `${runtimeApiRoot}/screenshot`;
 const virtualRuntimeClientId = 'virtual:pixifact-runtime-client';
 const resolvedVirtualRuntimeClientId = `\0${virtualRuntimeClientId}`;
+const pngSignature = Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]);
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
@@ -57,6 +59,27 @@ function isRuntimeRequest(value) {
         && typeof value.key === 'string'
         && value.key.length > 0;
 }
+function runtimeScreenshotResult(value) {
+    if (!isRecord(value)
+        || typeof value.runtimeId !== 'string'
+        || !Number.isInteger(value.width)
+        || Number(value.width) <= 0
+        || !Number.isInteger(value.height)
+        || Number(value.height) <= 0
+        || typeof value.dataUrl !== 'string') {
+        return undefined;
+    }
+    const match = value.dataUrl.match(/^data:image\/png;base64,([A-Za-z0-9+/]+={0,2})$/);
+    const png = match ? Buffer.from(match[1], 'base64') : undefined;
+    if (!png || !png.subarray(0, pngSignature.length).equals(pngSignature))
+        return undefined;
+    return {
+        runtimeId: value.runtimeId,
+        width: Number(value.width),
+        height: Number(value.height),
+        png,
+    };
+}
 export function createRuntimeHostSession(options) {
     const requestTimeoutMs = options.requestTimeoutMs ?? 5_000;
     const now = options.now ?? (() => new Date());
@@ -96,6 +119,29 @@ export function createRuntimeHostSession(options) {
             }
         }
     }
+    function forwardRequest(runtime, request, responseType) {
+        const requestId = `runtime-${++requestSequence}`;
+        return new Promise((resolve) => {
+            const timeout = setTimeout(() => {
+                settle(requestId, jsonResponse({
+                    ok: false,
+                    error: 'Pixifact Runtime request timed out.',
+                }, 504));
+            }, requestTimeoutMs);
+            pending.set(requestId, {
+                resolve,
+                runtimeId: runtime.runtimeId,
+                socket: runtime.socket,
+                responseType,
+                timeout,
+            });
+            runtime.socket.send(runtimeRequestEvent, {
+                requestId,
+                runtimeId: runtime.runtimeId,
+                request,
+            });
+        });
+    }
     function message(socket, event, data) {
         if (!sockets.has(socket))
             return;
@@ -122,9 +168,38 @@ export function createRuntimeHostSession(options) {
         const current = pending.get(data.requestId);
         if (!current || current.socket !== socket || current.runtimeId !== data.runtimeId)
             return;
-        settle(data.requestId, data.ok
-            ? jsonResponse(data.result)
-            : jsonResponse({ ok: false, error: data.error }, 422));
+        if (!data.ok) {
+            settle(data.requestId, jsonResponse({ ok: false, error: data.error }, 422));
+            return;
+        }
+        if (current.responseType === 'json') {
+            settle(data.requestId, jsonResponse(data.result));
+            return;
+        }
+        const screenshot = runtimeScreenshotResult(data.result);
+        if (!screenshot) {
+            settle(data.requestId, jsonResponse({
+                ok: false,
+                error: 'Pixifact Runtime returned invalid screenshot data.',
+            }, 502));
+            return;
+        }
+        if (screenshot.runtimeId !== data.runtimeId) {
+            settle(data.requestId, jsonResponse({
+                ok: false,
+                error: 'Pixifact Runtime returned a screenshot for a different runtime.',
+            }, 502));
+            return;
+        }
+        settle(data.requestId, new Response(screenshot.png, {
+            headers: {
+                'cache-control': 'no-store',
+                'content-type': 'image/png',
+                'x-pixifact-height': String(screenshot.height),
+                'x-pixifact-runtime': screenshot.runtimeId,
+                'x-pixifact-width': String(screenshot.width),
+            },
+        }));
     }
     async function fetchRequest(request) {
         const pathname = new URL(request.url).pathname;
@@ -150,6 +225,23 @@ export function createRuntimeHostSession(options) {
                     .sort((left, right) => left.connectedAt.localeCompare(right.connectedAt)),
             });
         }
+        if (pathname === runtimeScreenshotPath) {
+            if (request.method !== 'POST') {
+                return jsonResponse({ ok: false, error: 'Pixifact Runtime screenshot requests require POST.' }, 405);
+            }
+            const body = await request.json();
+            if (!isRecord(body) || typeof body.runtimeId !== 'string') {
+                return jsonResponse({ ok: false, error: 'Pixifact Runtime screenshot request is invalid.' }, 400);
+            }
+            const runtime = runtimes.get(body.runtimeId);
+            if (!runtime) {
+                return jsonResponse({
+                    ok: false,
+                    error: `Pixifact Runtime "${body.runtimeId}" is not connected.`,
+                }, 404);
+            }
+            return forwardRequest(runtime, { type: 'screenshot' }, 'screenshot');
+        }
         if (pathname !== `${runtimeApiRoot}/request`)
             return undefined;
         if (request.method !== 'POST') {
@@ -166,26 +258,7 @@ export function createRuntimeHostSession(options) {
                 error: `Pixifact Runtime "${body.runtimeId}" is not connected.`,
             }, 404);
         }
-        const requestId = `runtime-${++requestSequence}`;
-        return new Promise((resolve) => {
-            const timeout = setTimeout(() => {
-                settle(requestId, jsonResponse({
-                    ok: false,
-                    error: 'Pixifact Runtime request timed out.',
-                }, 504));
-            }, requestTimeoutMs);
-            pending.set(requestId, {
-                resolve,
-                runtimeId: runtime.runtimeId,
-                socket: runtime.socket,
-                timeout,
-            });
-            runtime.socket.send(runtimeRequestEvent, {
-                requestId,
-                runtimeId: runtime.runtimeId,
-                request: body.request,
-            });
-        });
+        return forwardRequest(runtime, body.request, 'json');
     }
     return {
         open,

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

@@ -1,9 +1,19 @@
-export interface PixifactScenesPluginOptions {
+import { type Plugin } from 'vite';
+export type PixifactPlatform = 'web' | 'wechat' | 'douyin';
+export interface PixifactPluginOptions {
     projectRoot?: string | URL;
-    generatedDir?: string;
 }
-export declare function pixifactScenesPlugin(options?: PixifactScenesPluginOptions): {
-    name: string;
-    resolveId(id: string): "\0pixifact:scenes" | undefined;
-    load(id: string): Promise<string | undefined>;
+export interface PixifactBuildReport {
+    mainPackageBytes: number;
+    outputDirectory: string;
+    platform: PixifactPlatform;
+    subpackages: Record<string, number>;
+    totalPackageBytes: number;
+}
+export declare function pixifact(options?: PixifactPluginOptions): Plugin[];
+export declare function pixifactBuildReporter(platform: PixifactPlatform, onReport: (report: PixifactBuildReport) => void): Plugin;
+export declare function loadPixifactEnv(projectRoot: string, mode: string): {
+    env: Record<string, string>;
+    platform: PixifactPlatform;
 };
+export declare function fileExists(filePath: string): Promise<boolean>;