pixifact 0.6.0 → 0.7.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/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>;