@pixifact/three 0.0.0-stage → 0.20.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,3 +1,48 @@
-# Temporary Holding Version
+# @pixifact/three
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Pixifact 可选 Three.js 插件。Three 绘制 3D 世界，Pixifact / PixiJS 绘制 2D UI，共用一个 WebGL2 Canvas 和 Application ticker。
+
+```bash
+bun add @pixifact/three three@0.186.1
+bun add -d @types/three@0.186.0
+```
+
+在现有 Vite 配置中注册：
+
+```ts
+import { pixifact } from 'pixifact/compiler-node';
+import { three } from '@pixifact/three/vite';
+
+export default {
+  plugins: [pixifact({ codePackages: { game: 'src/game.ts' } }), three()],
+};
+```
+
+在 `src/game.ts` 中创建 3D 层：
+
+```ts
+import { createThreeLayer } from '@pixifact/three';
+import { PerspectiveCamera, Scene } from 'three';
+import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
+import type { Application } from 'pixi.js';
+
+export function startGame(app: Application) {
+  const scene = new Scene();
+  const camera = new PerspectiveCamera(45, 1, 0.1, 100);
+  camera.position.z = 5;
+  const layer = createThreeLayer(app, { scene, camera });
+  const controls = new OrbitControls(camera, layer.input);
+  return { layer, controls };
+}
+```
+
+主入口使用 `pixifact:platform` 的 `createApplication({ preference: 'webgl' })`，再调用 `import('./game')`。沿用 `pixifact build --mode web/wechat/douyin`，引擎随游戏代码进入分包。
+
+- 原生 Three Scene、Camera、Mesh 与 `.scene` UI 可以组合使用。
+- UI 优先接收输入；`layer.input` 提供世界手势，`layer.raycast(event, objects)` 用于拾取。
+- 普通 glTF/GLB、外部纹理和内嵌图片支持小游戏资源通道及资源分包。资源 URL 可从 `Assets.resolver.resolve(alias).src` 获取。
+- Web 开发 Runtime 注册时传入 `captureScreenshot: layer.captureScreenshot`，截图包含 3D 和 UI。
+- `layer.destroy()` 释放插件 renderer 和输入，恢复 Pixi 绘制；共享 Canvas/context 保留。控件、模型 geometry/material/texture 按 Three 原生规则 dispose。
+- 需要 WebGL2；首版小游戏 loader 适配 Three r186。WASM、Draco/KTX2、3D 可视化编辑不在此版本范围内。
+
+[完整接入文档](https://github.com/hxg2050/pixifact/blob/main/docs/zh/three.md) · [三端示例](https://github.com/hxg2050/pixifact/tree/main/sample-projects/three-demo)

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { createThreeLayer } from './layer.js';
+export type { ThreeLayer, ThreeLayerOptions, ThreeScreenshot } from './layer.js';

package/dist/index.js

@@ -0,0 +1 @@
+export { createThreeLayer } from './layer.js';

package/dist/input.d.ts

@@ -0,0 +1,6 @@
+import { type Application } from 'pixi.js';
+/** 只供 Three 控件使用的局部事件面，不修改宿主 Canvas / document。 */
+export declare function createThreeInput(app: Application): {
+    element: HTMLElement;
+    destroy(): void;
+};

package/dist/input.js

@@ -0,0 +1,110 @@
+import { Container } from 'pixi.js';
+/** 只供 Three 控件使用的局部事件面，不修改宿主 Canvas / document。 */
+export function createThreeInput(app) {
+    const surface = new Container({ label: 'Three input', eventMode: 'static' });
+    // Pointer down 只来自 Canvas；无限命中面让 UI stage 的视口变换不影响世界输入。
+    surface.hitArea = { contains: () => true };
+    app.stage.addChildAt(surface, 0);
+    const listeners = new Map();
+    const active = new Map();
+    const captured = new Set();
+    const element = {
+        style: app.canvas.style,
+        get clientWidth() { return app.canvas.getBoundingClientRect().width; },
+        get clientHeight() { return app.canvas.getBoundingClientRect().height; },
+        get ownerDocument() { return element; },
+        getRootNode: () => element,
+        getBoundingClientRect: () => app.canvas.getBoundingClientRect(),
+        setPointerCapture: (id) => { captured.add(id); },
+        hasPointerCapture: (id) => captured.has(id),
+        releasePointerCapture: (id) => { captured.delete(id); },
+        addEventListener(type, listener, options) {
+            const current = listeners.get(type) ?? new Map();
+            current.set(listener, { once: typeof options === 'object' && options.once === true });
+            listeners.set(type, current);
+        },
+        removeEventListener(type, listener) {
+            listeners.get(type)?.delete(listener);
+        },
+    };
+    const emit = (event) => {
+        for (const [listener, options] of [...(listeners.get(event.type) ?? [])]) {
+            if (options.once)
+                listeners.get(event.type).delete(listener);
+            if (typeof listener === 'function')
+                listener.call(element, event);
+            else
+                listener.handleEvent(event);
+            if (event.cancelBubble)
+                break;
+        }
+    };
+    const dispatch = (type, source) => {
+        const pointer = source;
+        const wheel = source;
+        const nativeEvent = source.nativeEvent;
+        let prevented = false;
+        const event = {
+            type, target: element, currentTarget: element,
+            clientX: source.clientX, clientY: source.clientY,
+            pageX: source.pageX, pageY: source.pageY,
+            pointerId: pointer.pointerId, pointerType: pointer.pointerType, isPrimary: pointer.isPrimary,
+            button: source.button, buttons: source.buttons,
+            altKey: source.altKey, ctrlKey: source.ctrlKey, metaKey: source.metaKey, shiftKey: source.shiftKey,
+            deltaX: wheel.deltaX, deltaY: wheel.deltaY, deltaZ: wheel.deltaZ, deltaMode: wheel.deltaMode,
+            get defaultPrevented() { return prevented; },
+            preventDefault() {
+                prevented = true;
+                if (nativeEvent && 'preventDefault' in nativeEvent)
+                    nativeEvent.preventDefault();
+            },
+            stopPropagation() { },
+            cancelBubble: false,
+            stopImmediatePropagation() { event.cancelBubble = true; },
+        };
+        emit(event);
+        return event;
+    };
+    const down = (event) => {
+        if (event.target !== surface)
+            return;
+        active.set(event.pointerId, dispatch('pointerdown', event));
+    };
+    const move = (event) => {
+        if (active.has(event.pointerId))
+            active.set(event.pointerId, dispatch('pointermove', event));
+        else if (event.target === surface)
+            dispatch('pointermove', event);
+    };
+    const up = (event) => {
+        if (!active.delete(event.pointerId))
+            return;
+        dispatch('pointerup', event);
+        captured.delete(event.pointerId);
+    };
+    const wheel = (event) => {
+        if (event.target === surface)
+            dispatch('wheel', event);
+    };
+    const boundary = app.renderer.events.rootBoundary.dispatch;
+    boundary.on('pointerdown', down);
+    boundary.on('pointermove', move);
+    boundary.on('pointerup', up);
+    boundary.on('wheel', wheel);
+    surface.on('pointerupoutside', up);
+    return {
+        element: element,
+        destroy() {
+            for (const event of active.values())
+                emit({ ...event, type: 'pointercancel' });
+            active.clear();
+            captured.clear();
+            boundary.off('pointerdown', down);
+            boundary.off('pointermove', move);
+            boundary.off('pointerup', up);
+            boundary.off('wheel', wheel);
+            listeners.clear();
+            surface.destroy();
+        },
+    };
+}

package/dist/layer.d.ts

@@ -0,0 +1,33 @@
+import { type Application } from 'pixi.js';
+import { Raycaster, WebGLRenderer, type Camera, type Object3D, type Scene, type WebGLRendererParameters } from 'three';
+export interface ThreeLayerOptions {
+    scene: Scene;
+    camera: Camera;
+    rendererOptions?: Omit<WebGLRendererParameters, 'canvas' | 'context'>;
+    /** 用于多 pass、后处理等原生 Three 绘制。默认调用 renderer.render(scene, camera)。 */
+    renderScene?: (renderer: WebGLRenderer, scene: Scene, camera: Camera) => void;
+    /** 自定义投影或布局；透视相机的 aspect 由插件自动更新。 */
+    onResize?: (width: number, height: number) => void;
+}
+export interface ThreeScreenshot {
+    width: number;
+    height: number;
+    dataUrl: string;
+}
+export interface ThreeLayer {
+    readonly renderer: WebGLRenderer;
+    readonly scene: Scene;
+    readonly camera: Camera;
+    /** 交给 OrbitControls 等控件的输入元素，只接收未被 UI 占用的手势。 */
+    readonly input: HTMLElement;
+    raycast(event: {
+        clientX: number;
+        clientY: number;
+    }, objects: Object3D[], recursive?: boolean): ReturnType<Raycaster['intersectObjects']>;
+    render(): void;
+    /** Web Runtime 的完整合成截图；与 registerPixiRuntime 的 captureScreenshot 选项配合使用。 */
+    captureScreenshot(): ThreeScreenshot;
+    /** 只释放插件拥有的 renderer/输入；模型、材质、纹理由游戏释放。 */
+    destroy(): void;
+}
+export declare function createThreeLayer(app: Application, options: ThreeLayerOptions): ThreeLayer;

package/dist/layer.js

@@ -0,0 +1,83 @@
+import { DOMAdapter, RendererType, UPDATE_PRIORITY } from 'pixi.js';
+import { Raycaster, Vector2, WebGLRenderer } from 'three';
+import { createThreeInput } from './input.js';
+export function createThreeLayer(app, options) {
+    const pixi = app.renderer;
+    if (pixi.type !== RendererType.WEBGL || pixi.context.webGLVersion !== 2) {
+        throw new Error('@pixifact/three 需要 WebGL2 Application；创建时设置 preference: "webgl"。');
+    }
+    const { scene, camera } = options;
+    // Pixi 初始化纹理后可能保留 premultiply unpack 状态；Three 构造时就会上传 3D 占位纹理。
+    pixi.resetState();
+    const renderer = new WebGLRenderer({ ...options.rendererOptions, canvas: app.canvas, context: pixi.gl });
+    const input = createThreeInput(app);
+    const raycaster = new Raycaster();
+    const pointer = new Vector2();
+    const originalRender = app.render;
+    const originalDestroy = app.destroy;
+    let width = -1;
+    let height = -1;
+    let resolution = -1;
+    let destroyed = false;
+    const layer = {
+        renderer, scene, camera, input: input.element,
+        raycast(event, objects, recursive = true) {
+            const rect = app.canvas.getBoundingClientRect();
+            pointer.set(((event.clientX - rect.left) / rect.width) * 2 - 1, 1 - ((event.clientY - rect.top) / rect.height) * 2);
+            scene.updateMatrixWorld();
+            camera.updateMatrixWorld();
+            raycaster.setFromCamera(pointer, camera);
+            return raycaster.intersectObjects(objects, recursive);
+        },
+        render() {
+            if (width !== app.screen.width || height !== app.screen.height || resolution !== pixi.resolution) {
+                width = app.screen.width;
+                height = app.screen.height;
+                resolution = pixi.resolution;
+                renderer.setDrawingBufferSize(width, height, resolution);
+                if (camera.isPerspectiveCamera) {
+                    camera.aspect = width / height;
+                    camera.updateProjectionMatrix();
+                }
+                options.onResize?.(width, height);
+            }
+            renderer.resetState();
+            renderer.setRenderTarget(null);
+            if (options.renderScene)
+                options.renderScene(renderer, scene, camera);
+            else
+                renderer.render(scene, camera);
+            pixi.resetState();
+            pixi.render({ container: app.stage, clear: false });
+        },
+        captureScreenshot() {
+            layer.render();
+            const captureWidth = Math.max(1, Math.floor(app.screen.width));
+            const captureHeight = Math.max(1, Math.floor(app.screen.height));
+            const canvas = DOMAdapter.get().createCanvas(captureWidth, captureHeight);
+            const context = canvas.getContext('2d');
+            context.drawImage(app.canvas, 0, 0, captureWidth, captureHeight);
+            return { width: captureWidth, height: captureHeight, dataUrl: canvas.toDataURL('image/png') };
+        },
+        destroy() {
+            if (destroyed)
+                return;
+            destroyed = true;
+            app.ticker.remove(layer.render, app);
+            app.render = originalRender;
+            app.destroy = originalDestroy;
+            app.ticker.add(originalRender, app, UPDATE_PRIORITY.LOW);
+            input.destroy();
+            renderer.dispose();
+            pixi.resetState();
+        },
+    };
+    app.ticker.remove(originalRender, app);
+    app.render = layer.render;
+    app.ticker.add(layer.render, app, UPDATE_PRIORITY.LOW);
+    app.destroy = (...args) => {
+        layer.destroy();
+        originalDestroy.apply(app, args);
+    };
+    return layer;
+}

package/dist/nativeLoaders.d.ts

@@ -0,0 +1,17 @@
+import { Loader } from 'three/src/loaders/Loader.js';
+type Progress = (event: ProgressEvent) => void;
+type Failure = (error: unknown) => void;
+/** Three 原生 Loader 协议，传输复用 Pixifact；不依赖浏览器 Request/Response/stream。 */
+export declare class FileLoader extends Loader {
+    responseType: string;
+    mimeType: string;
+    private generation;
+    load(url: string, onLoad: (data: unknown) => void, onProgress?: Progress, onError?: Failure): void;
+    setResponseType(value: string): this;
+    setMimeType(value: string): this;
+    abort(): this;
+}
+export declare class ImageLoader extends Loader<HTMLImageElement> {
+    load(url: string, onLoad: (image: HTMLImageElement) => void, _onProgress?: Progress, onError?: Failure): HTMLImageElement;
+}
+export {};

package/dist/nativeLoaders.js

@@ -0,0 +1,92 @@
+import { DOMAdapter } from 'pixi.js';
+import { Cache } from 'three/src/loaders/Cache.js';
+import { Loader } from 'three/src/loaders/Loader.js';
+import { resources } from 'pixifact:three-platform';
+import { NativeBlob, NativeTextDecoder } from './nativeResources.js';
+/** Three 原生 Loader 协议，传输复用 Pixifact；不依赖浏览器 Request/Response/stream。 */
+export class FileLoader extends Loader {
+    responseType = '';
+    mimeType = '';
+    generation = 0;
+    load(url, onLoad, onProgress, onError) {
+        url = this.manager.resolveURL(this.path + url);
+        const generation = this.generation;
+        this.manager.itemStart(url);
+        void (async () => {
+            try {
+                let data = Cache.get(`file:${url}`);
+                if (data === undefined) {
+                    const buffer = await resources.read(url);
+                    if (generation !== this.generation)
+                        throw new Error(`Three 资源加载已取消: ${url}`);
+                    onProgress?.({ type: 'progress', lengthComputable: true, loaded: buffer.byteLength, total: buffer.byteLength });
+                    if (this.responseType === 'arraybuffer')
+                        data = buffer;
+                    else if (this.responseType === 'blob')
+                        data = new NativeBlob([buffer], { type: this.mimeType });
+                    else {
+                        const text = new NativeTextDecoder().decode(buffer);
+                        if (this.responseType === 'json')
+                            data = JSON.parse(text);
+                        else if (this.responseType === 'document')
+                            data = new DOMParser().parseFromString(text, this.mimeType);
+                        else
+                            data = text;
+                    }
+                    Cache.add(`file:${url}`, data);
+                }
+                onLoad?.(data);
+            }
+            catch (error) {
+                if (onError)
+                    onError(error);
+                else
+                    console.error(error);
+                this.manager.itemError(url);
+            }
+            finally {
+                this.manager.itemEnd(url);
+            }
+        })();
+    }
+    setResponseType(value) { this.responseType = value; return this; }
+    setMimeType(value) { this.mimeType = value; return this; }
+    abort() { this.generation++; return this; }
+}
+export class ImageLoader extends Loader {
+    load(url, onLoad, _onProgress, onError) {
+        url = this.manager.resolveURL(this.path + url);
+        const image = DOMAdapter.get().createImage();
+        image.crossOrigin = this.crossOrigin;
+        this.manager.itemStart(url);
+        void (async () => {
+            try {
+                const prepared = await resources.prepareImage(url);
+                try {
+                    await new Promise((resolve, reject) => {
+                        image.onload = () => resolve();
+                        image.onerror = reject;
+                        image.src = prepared.src;
+                    });
+                }
+                finally {
+                    await prepared.release?.();
+                }
+                onLoad?.(image);
+            }
+            catch (error) {
+                if (onError)
+                    onError(error);
+                else
+                    console.error(error);
+                this.manager.itemError(url);
+            }
+            finally {
+                image.onload = null;
+                image.onerror = null;
+                this.manager.itemEnd(url);
+            }
+        })();
+        return image;
+    }
+}

package/dist/nativeResources.d.ts

@@ -0,0 +1,50 @@
+import { type MiniGameApi } from 'pixifact/internal/minigame';
+export interface ThreeMiniGameApi extends MiniGameApi {
+    env: {
+        USER_DATA_PATH: string;
+    };
+    base64ToArrayBuffer(data: string): ArrayBuffer;
+    getFileSystemManager(): ReturnType<MiniGameApi['getFileSystemManager']> & {
+        writeFile(options: {
+            filePath: string;
+            data: ArrayBuffer;
+            success(): void;
+            fail(error: {
+                errMsg: string;
+            }): void;
+        }): void;
+        unlink(options: {
+            filePath: string;
+            success(): void;
+            fail(error: {
+                errMsg: string;
+            }): void;
+        }): void;
+    };
+}
+/** glTF 只需要 UTF-8 解码，复用小游戏资源层实现，不修改全局 TextDecoder。 */
+export declare class NativeTextDecoder {
+    decode(input: ArrayBuffer | ArrayBufferView): string;
+}
+export declare class NativeBlob {
+    readonly type: string;
+    readonly bytes: Uint8Array;
+    constructor(parts: ArrayBuffer[], options?: {
+        type?: string;
+    });
+    arrayBuffer(): Promise<ArrayBuffer>;
+}
+export declare function createNativeThreeResources(getApi: () => ThreeMiniGameApi, platform: string): {
+    Blob: typeof NativeBlob;
+    TextDecoder: typeof NativeTextDecoder;
+    URL: {
+        createObjectURL(blob: NativeBlob): string;
+        revokeObjectURL(url: string): void;
+    };
+    read(url: string): Promise<ArrayBuffer>;
+    prepareImage(url: string): Promise<{
+        src: string;
+        release?: () => Promise<void>;
+    }>;
+};
+export type NativeThreeResources = ReturnType<typeof createNativeThreeResources>;

package/dist/nativeResources.js

@@ -0,0 +1,86 @@
+import { DOMAdapter } from 'pixi.js';
+import { createMiniGameSubpackageLoader, decodeUtf8, encodeUtf8, miniGameResourceSubpackage } from 'pixifact/internal/minigame';
+/** glTF 只需要 UTF-8 解码，复用小游戏资源层实现，不修改全局 TextDecoder。 */
+export class NativeTextDecoder {
+    decode(input) {
+        const buffer = ArrayBuffer.isView(input)
+            ? input.buffer.slice(input.byteOffset, input.byteOffset + input.byteLength)
+            : input;
+        return decodeUtf8(buffer).replace(/^\uFEFF/, '');
+    }
+}
+export class NativeBlob {
+    type;
+    bytes;
+    constructor(parts, options = {}) {
+        this.type = options.type ?? '';
+        this.bytes = new Uint8Array(parts.reduce((size, part) => size + part.byteLength, 0));
+        let offset = 0;
+        for (const part of parts) {
+            this.bytes.set(new Uint8Array(part), offset);
+            offset += part.byteLength;
+        }
+    }
+    async arrayBuffer() { return this.bytes.slice().buffer; }
+}
+let nextResourceId = 0;
+export function createNativeThreeResources(getApi, platform) {
+    const blobs = new Map();
+    const loadPackage = createMiniGameSubpackageLoader(getApi, platform);
+    const decodeData = (url) => {
+        const comma = url.indexOf(',');
+        const header = url.slice(5, comma);
+        const payload = url.slice(comma + 1);
+        return {
+            type: header.split(';')[0],
+            data: header.endsWith(';base64') ? getApi().base64ToArrayBuffer(payload) : encodeUtf8(decodeURIComponent(payload)),
+        };
+    };
+    return {
+        Blob: NativeBlob,
+        TextDecoder: NativeTextDecoder,
+        URL: {
+            createObjectURL(blob) {
+                const url = `blob:pixifact-three/${++nextResourceId}`;
+                blobs.set(url, blob);
+                return url;
+            },
+            revokeObjectURL(url) { blobs.delete(url); },
+        },
+        async read(url) {
+            if (url.startsWith('data:'))
+                return decodeData(url).data;
+            if (url.startsWith('blob:pixifact-three/'))
+                return blobs.get(url).arrayBuffer();
+            const response = await DOMAdapter.get().fetch(url);
+            if (!response.ok)
+                throw new Error(`Three 资源加载失败 (${response.status}): ${url}`);
+            return response.arrayBuffer();
+        },
+        async prepareImage(url) {
+            const pack = miniGameResourceSubpackage(url);
+            if (pack)
+                await loadPackage(pack);
+            if (!url.startsWith('data:') && !url.startsWith('blob:pixifact-three/'))
+                return { src: url };
+            const embedded = url.startsWith('data:')
+                ? decodeData(url)
+                : { type: blobs.get(url).type, data: await blobs.get(url).arrayBuffer() };
+            const extension = embedded.type.split('/')[1].replace('jpeg', 'jpg');
+            const api = getApi();
+            const fs = api.getFileSystemManager();
+            const src = `${api.env.USER_DATA_PATH}/pixifact-three-${Date.now()}-${++nextResourceId}.${extension}`;
+            await new Promise((resolve, reject) => fs.writeFile({
+                filePath: src, data: embedded.data, success: resolve,
+                fail: (error) => reject(new Error(error.errMsg)),
+            }));
+            return {
+                src,
+                release: () => new Promise((resolve, reject) => fs.unlink({
+                    filePath: src, success: resolve,
+                    fail: (error) => reject(new Error(error.errMsg)),
+                })),
+            };
+        },
+    };
+}

package/dist/vite.d.ts

@@ -0,0 +1,3 @@
+import type { Plugin } from 'vite';
+/** 与 pixifact() 一起注册，小游戏端局部适配 Three r186 资源加载。 */
+export declare function three(): Plugin;

package/dist/vite.js

@@ -0,0 +1,49 @@
+import { loadPixifactEnv } from 'pixifact/compiler-node';
+const platformModule = 'pixifact:three-platform';
+const virtualPlatform = '\0' + platformModule;
+/** 与 pixifact() 一起注册，小游戏端局部适配 Three r186 资源加载。 */
+export function three() {
+    let platform;
+    return {
+        name: 'pixifact-three',
+        enforce: 'pre',
+        config() { return { resolve: { dedupe: ['pixi.js', 'three', '@pixifact/three'] } }; },
+        configResolved(config) { platform = loadPixifactEnv(config.root, config.mode).platform; },
+        async resolveId(id, importer) {
+            if (platform === 'web')
+                return;
+            if (id === platformModule)
+                return virtualPlatform;
+            // Three 的 build 入口将 loader 内联；使用同一份源码模块，保留可替换的 loader 边界。
+            if (id === 'three')
+                return this.resolve('three/src/Three.js', importer, { skipSelf: true });
+            return undefined;
+        },
+        load(id) {
+            if (id !== virtualPlatform)
+                return;
+            return `import { createNativeThreeResources } from '@pixifact/three/internal/resources';
+export const resources = createNativeThreeResources(() => ${platform === 'wechat' ? 'wx' : 'tt'}, ${JSON.stringify(platform)});`;
+        },
+        transform(code, id) {
+            if (platform === 'web')
+                return;
+            const source = id.replaceAll('\\', '/').split('?')[0];
+            const loader = source.match(/\/three\/src\/loaders\/(FileLoader|ImageLoader)\.js$/)?.[1];
+            if (loader)
+                return { code: `export { ${loader} } from '@pixifact/three/internal/loaders';`, map: null };
+            if (source.endsWith('/three/examples/jsm/loaders/GLTFLoader.js')) {
+                return {
+                    code: `import { resources as __pixifactResources } from '${platformModule}';
+const Blob = __pixifactResources.Blob;
+const TextDecoder = __pixifactResources.TextDecoder;
+const self = { URL: __pixifactResources.URL };
+const createImageBitmap = undefined;
+${code}`,
+                    map: null,
+                };
+            }
+            return undefined;
+        },
+    };
+}

package/package.json

@@ -1,6 +1,53 @@
 {
   "name": "@pixifact/three",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.20.0",
+  "description": "Pixifact 可选 Three.js 3D 世界与 2D UI 合成插件。",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist/",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/hxg2050/pixifact",
+    "directory": "packages/three"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js"
+    },
+    "./vite": {
+      "types": "./dist/vite.d.ts",
+      "import": "./dist/vite.js",
+      "require": "./dist/vite.js"
+    },
+    "./internal/loaders": {
+      "types": "./dist/nativeLoaders.d.ts",
+      "import": "./dist/nativeLoaders.js"
+    },
+    "./internal/resources": {
+      "types": "./dist/nativeResources.d.ts",
+      "import": "./dist/nativeResources.js"
+    }
+  },
+  "scripts": {
+    "build": "bun ../pixifact/scripts/clean-dist.mjs dist && bunx --no-install tsc -p tsconfig.build.json && bun ../pixifact/scripts/fix-dist-esm-imports.mjs dist"
+  },
+  "peerDependencies": {
+    "pixifact": ">=0.20.0 <1",
+    "pixi.js": ">=8.18.1 <9",
+    "three": ">=0.186.1 <0.187.0",
+    "vite": ">=8.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "license": "MIT"
+}