@guoquan.net/flow-engine 0.1.2

package/README.md

@@ -0,0 +1,86 @@
+# Flow (服喽) 🌊
+`@guoquan.net/flow-engine`
+
+[![CI](https://github.com/guoquan/flow-engine/actions/workflows/ci.yml/badge.svg)](https://github.com/guoquan/flow-engine/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/guoquan/flow-engine/graph/badge.svg?token=2T5SGUBMK4)](https://codecov.io/gh/guoquan/flow-engine)
+[![Deploy to GitHub Pages](https://github.com/guoquan/flow-engine/actions/workflows/deploy.yml/badge.svg)](https://github.com/guoquan/flow-engine/actions/workflows/deploy.yml)
+
+[English](#english) | [中文](#中文)
+
+---
+
+## English
+
+> **"Flow: Convincing at first breath."**
+
+**Flow** (distributed as `@guoquan.net/flow-engine`) is a high-performance, lightweight web-based digital human engine. It empowers web applications with lifelike AI avatars through simple API-driven interactions.
+
+### 🌟 Highlights
+- **Modern Rendering**: Based on WebGPU for next-gen performance and visual quality.
+- **Data-Driven**: Animation and behavior fully controlled via JSON configuration.
+- **Zero-Dependency Core**: Pure frontend architecture, easy to integrate into any project.
+
+### 🛠 Tech Stack
+- **Core**: TypeScript
+- **Rendering**: Three.js (WebGPU Renderer)
+- **Build**: Vite
+
+### 📦 Installation
+
+You can install the SDK directly from GitHub:
+
+```bash
+# Using npm
+npm install github:guoquan/flow-engine
+
+# Using pnpm
+pnpm add github:guoquan/flow-engine
+```
+
+To use a specific version (recommended):
+
+```bash
+npm install github:guoquan/flow-engine#v0.1.0
+```
+
+### 📚 Documentation
+Please visit **[docs/](./docs/)** for the full documentation and API references.
+
+---
+
+## 中文
+
+> **"一开口，就服喽。"**
+
+**Flow** (包名称：`@guoquan.net/flow-engine`) 是一个高性能、轻量级的 Web 端数字人引擎。它旨在通过简单的 API 驱动，为 Web 应用赋予栩栩如生的 AI 化身交互能力。
+
+### 🌟 项目亮点
+- **现代化渲染**：基于 WebGPU，提供下一代渲染性能与视觉效果。
+- **数据驱动**：动画与行为完全通过 JSON 配置文件控制。
+- **零依赖核心**：纯前端架构，无需后端即可运行，易于集成。
+
+### 🛠 技术栈
+- **核心**: TypeScript
+- **渲染**: Three.js (WebGPU Renderer)
+- **构建**: Vite
+
+### 📦 安装
+
+你可以直接从 GitHub 安装该 SDK：
+
+```bash
+# 使用 npm
+npm install github:guoquan/flow-engine
+
+# 使用 pnpm
+pnpm add github:guoquan/flow-engine
+```
+
+建议安装特定版本以保证稳定性：
+
+```bash
+npm install github:guoquan/flow-engine#v0.1.0
+```
+
+### 📚 文档索引
+请访问 **[docs/](./docs/)** 查看完整文档与 API 说明。

package/dist/assets/avatars/default/config.json

@@ -0,0 +1,8 @@
+{
+  "id": "flow-bot-01",
+  "name": "Flow Bot",
+  "modelSrc": "model.glb",
+  "scale": 1.5,
+  "initialPosition": [0, -1, 0],
+  "version": "1.0.0"
+}

package/dist/assets/avatars/expressive/config.json

@@ -0,0 +1,37 @@
+{
+  "name": "Robot Expressive",
+  "modelSrc": "model.glb",
+  "scale": 0.3,
+  "initialPosition": [0, 0, 0],
+  "animations": {
+    "defaultState": "idle",
+    "states": {
+      "idle": {
+        "clipName": "Idle",
+        "loop": true,
+        "timeScale": 0.4,
+        "fadeDuration": 1.0
+      },
+      "wave": {
+        "clipName": "Wave",
+        "loop": false,
+        "next": "idle",
+        "fadeDuration": 0.5
+      },
+      "dance": {
+        "clipName": "Dance",
+        "loop": false,
+        "next": "idle",
+        "timeScale": 1.2,
+        "fadeDuration": 0.5
+      },
+      "death": {
+        "clipName": "Death",
+        "loop": false,
+        "next": "idle",
+        "fadeDuration": 0.8,
+        "holdDuration": 3.0
+      }
+    }
+  }
+}

package/dist/assets/stages/default/config.json

@@ -0,0 +1,11 @@
+{
+  "name": "Sci-Fi Podium",
+  "position": [0, 0, 0],
+  "scale": 1.0,
+  "animations": {
+    "defaultState": "idle",
+    "states": {
+      "idle": { "clipName": "Idle", "loop": true }
+    }
+  }
+}

package/dist/core/AnimationController.d.ts

@@ -0,0 +1,31 @@
+import { AnimationStateConfig } from '../types';
+import * as THREE from 'three';
+export declare class AnimationController {
+    private mixer;
+    private clips;
+    private states;
+    private activeActions;
+    private currentState;
+    private defaultState;
+    constructor(model: THREE.Object3D, animations: THREE.AnimationClip[]);
+    /**
+     * Initialize with configuration
+     */
+    init(config: {
+        defaultState: string;
+        states: Record<string, AnimationStateConfig>;
+    }): void;
+    /**
+     * Update mixer (call this every frame)
+     */
+    update(delta: number): void;
+    /**
+     * Play a state
+     */
+    play(stateName: string, forceReset?: boolean): void;
+    private onFinished;
+    /**
+     * Finds an animation clip by name using exact, case-insensitive, or fuzzy matching.
+     */
+    private findClip;
+}

package/dist/core/AvatarLoader.d.ts

@@ -0,0 +1,29 @@
+import { AvatarConfig } from '../types';
+import * as THREE from 'three';
+/**
+ * AvatarLoader
+ * 负责加载数字人的配置和模型资源
+ */
+export declare class AvatarLoader {
+    private loader;
+    constructor();
+    /**
+     * 加载数字人
+     * @param configUrl 指向 config.json 的 URL
+     * @returns Promise<{ model: THREE.Object3D, config: AvatarConfig, animations: THREE.AnimationClip[] }>
+     */
+    load(configUrl: string): Promise<{
+        model: THREE.Object3D;
+        config: AvatarConfig;
+        animations: THREE.AnimationClip[];
+    }>;
+    /**
+     * 应用配置到模型
+     */
+    private applyConfig;
+    /**
+     * 创建一个占位符 Avatar (当模型文件缺失时)
+     * 生成一个简单的机器人形状
+     */
+    private createFallbackAvatar;
+}

package/dist/core/FlowEngine.d.ts

@@ -0,0 +1,31 @@
+export declare class FlowEngine {
+    private container;
+    private scene;
+    private camera;
+    private renderer;
+    private controls;
+    private clock;
+    private loader;
+    private stageLoader;
+    private avatarModel;
+    private stageModel;
+    private animController;
+    private stageAnimController;
+    constructor(containerId: string);
+    private setupLights;
+    /**
+     * Load an avatar by config URL
+     */
+    loadAvatar(configUrl: string): Promise<void>;
+    /**
+     * Load a stage (podium/scene) by config URL
+     */
+    loadStage(configUrl: string): Promise<void>;
+    private onWindowResize;
+    isAutoRotate: boolean;
+    /**
+     * Play a specific action
+     */
+    playAction(action: string): void;
+    private animate;
+}

package/dist/core/StageLoader.d.ts

@@ -0,0 +1,16 @@
+import { StageConfig } from '../types';
+import * as THREE from 'three';
+export declare class StageLoader {
+    private loader;
+    constructor();
+    load(configUrl: string): Promise<{
+        model: THREE.Object3D;
+        config: StageConfig;
+        animations: THREE.AnimationClip[];
+    }>;
+    private applyConfig;
+    /**
+     * Generates a cool Sci-Fi Podium if no model is provided
+     */
+    private createProceduralStage;
+}

package/dist/flow.es.js

@@ -0,0 +1,253 @@
+import * as i from "three";
+import { WebGPURenderer as g } from "three/webgpu";
+import { OrbitControls as y } from "three/examples/jsm/controls/OrbitControls.js";
+import { GLTFLoader as f } from "three/examples/jsm/loaders/GLTFLoader.js";
+class M {
+  loader;
+  constructor() {
+    this.loader = new f();
+  }
+  /**
+   * 加载数字人
+   * @param configUrl 指向 config.json 的 URL
+   * @returns Promise<{ model: THREE.Object3D, config: AvatarConfig, animations: THREE.AnimationClip[] }>
+   */
+  async load(t) {
+    console.log(`[Flow] Loading avatar config from: ${t}`);
+    try {
+      const e = await fetch(t);
+      if (!e.ok)
+        throw new Error(`Failed to load config: ${e.statusText}`);
+      const o = await e.json(), n = t.substring(0, t.lastIndexOf("/") + 1) + o.modelSrc;
+      console.log(`[Flow] Config loaded. Loading model from: ${n}`);
+      let r, s = [];
+      try {
+        const l = await this.loader.loadAsync(n);
+        r = l.scene, s = l.animations || [];
+      } catch (l) {
+        console.warn(`[Flow] Failed to load 3D model at ${n}. Using fallback placeholder.`, l), r = this.createFallbackAvatar();
+      }
+      return this.applyConfig(r, o), { model: r, config: o, animations: s };
+    } catch (e) {
+      throw console.error("[Flow] Error loading avatar:", e), e;
+    }
+  }
+  /**
+   * 应用配置到模型
+   */
+  applyConfig(t, e) {
+    e.scale && t.scale.setScalar(e.scale), e.initialPosition && t.position.set(...e.initialPosition), t.traverse((o) => {
+      o.isMesh && (o.castShadow = !0, o.receiveShadow = !0);
+    });
+  }
+  /**
+   * 创建一个占位符 Avatar (当模型文件缺失时)
+   * 生成一个简单的机器人形状
+   */
+  createFallbackAvatar() {
+    const t = new i.Group(), e = new i.MeshStandardMaterial({
+      color: 54015,
+      roughness: 0.3,
+      metalness: 0.8
+    }), o = new i.BoxGeometry(0.8, 0.9, 0.8), a = new i.Mesh(o, e);
+    a.position.y = 1.5, a.name = "Head", t.add(a);
+    const n = new i.SphereGeometry(0.1), r = new i.MeshBasicMaterial({ color: 16777215 }), s = new i.Mesh(n, r);
+    s.position.set(-0.2, 1.5, 0.4), t.add(s);
+    const l = new i.Mesh(n, r);
+    l.position.set(0.2, 1.5, 0.4), t.add(l);
+    const d = new i.CylinderGeometry(0.6, 0.4, 1.5, 8), c = new i.Mesh(d, e);
+    c.position.y = 0.5, c.name = "Body", t.add(c);
+    const h = new i.CapsuleGeometry(0.15, 1), p = new i.Mesh(h, e);
+    p.position.set(-0.9, 0.8, 0), p.rotation.z = Math.PI / 4, p.name = "LeftArm", t.add(p);
+    const w = new i.Mesh(h, e);
+    return w.position.set(0.9, 0.8, 0), w.rotation.z = -Math.PI / 4, w.name = "RightArm", t.add(w), t;
+  }
+}
+class S {
+  loader;
+  constructor() {
+    this.loader = new f();
+  }
+  async load(t) {
+    try {
+      const e = await fetch(t);
+      if (!e.ok) throw new Error("Failed to load stage config");
+      const o = await e.json();
+      let a, n = [];
+      if (o.modelSrc) {
+        const s = t.substring(0, t.lastIndexOf("/") + 1) + o.modelSrc, l = await this.loader.loadAsync(s);
+        a = l.scene, n = l.animations || [];
+      } else
+        a = this.createProceduralStage();
+      return this.applyConfig(a, o), { model: a, config: o, animations: n };
+    } catch (e) {
+      throw console.error("[Flow] Stage load error:", e), e;
+    }
+  }
+  applyConfig(t, e) {
+    e.scale && t.scale.setScalar(e.scale), e.position && t.position.set(...e.position), e.rotation && t.rotation.set(...e.rotation), t.traverse((o) => {
+      o.isMesh && (o.receiveShadow = !0, o.castShadow = !0);
+    });
+  }
+  /**
+   * Generates a cool Sci-Fi Podium if no model is provided
+   */
+  createProceduralStage() {
+    const t = new i.Group(), e = new i.CylinderGeometry(2, 2.2, 0.2, 32), o = new i.MeshStandardMaterial({ color: 2236962, roughness: 0.2, metalness: 0.8 }), a = new i.Mesh(e, o);
+    a.position.y = -0.1, t.add(a);
+    const n = new i.TorusGeometry(1.8, 0.05, 16, 100), r = new i.MeshBasicMaterial({ color: 54015 }), s = new i.Mesh(n, r);
+    s.rotation.x = -Math.PI / 2, s.position.y = 0.01, t.add(s);
+    const l = new i.BoxGeometry(0.5, 0.05, 0.5);
+    for (let d = 0; d < 4; d++) {
+      const c = new i.Mesh(l, o), h = d / 4 * Math.PI * 2;
+      c.position.set(Math.cos(h) * 2.5, 0, Math.sin(h) * 2.5), c.lookAt(0, 0, 0), t.add(c);
+    }
+    return t;
+  }
+}
+class u {
+  mixer;
+  clips;
+  states = {};
+  activeActions = /* @__PURE__ */ new Map();
+  currentState = null;
+  defaultState = "idle";
+  constructor(t, e) {
+    this.mixer = new i.AnimationMixer(t), this.clips = e, this.mixer.addEventListener("finished", this.onFinished.bind(this));
+  }
+  /**
+   * Initialize with configuration
+   */
+  init(t) {
+    this.defaultState = t.defaultState, this.states = t.states, Object.entries(this.states).forEach(([e, o]) => {
+      this.findClip(o.clipName) || console.warn(`[AnimationController] Clip "${o.clipName}" for state "${e}" not found.`);
+    }), this.play(this.defaultState);
+  }
+  /**
+   * Update mixer (call this every frame)
+   */
+  update(t) {
+    this.mixer.update(t);
+  }
+  /**
+   * Play a state
+   */
+  play(t, e = !1) {
+    const o = this.states[t];
+    if (!o) {
+      console.warn(`[AnimationController] State "${t}" not defined.`);
+      return;
+    }
+    const a = this.findClip(o.clipName);
+    if (!a || this.currentState === t && !e) return;
+    const n = this.mixer.clipAction(a);
+    n.setLoop(o.loop ? i.LoopRepeat : i.LoopOnce, o.loop ? 1 / 0 : 1), n.clampWhenFinished = !o.loop, n.timeScale = o.timeScale ?? 1;
+    const r = o.fadeDuration ?? 0.3;
+    if (this.currentState) {
+      const s = this.activeActions.get(this.currentState);
+      s && s !== n ? (s.fadeOut(r), n.reset(), n.fadeIn(r), n.play()) : n.reset().play();
+    } else
+      n.reset().play();
+    this.activeActions.set(t, n), this.currentState = t, console.log(`[Anim] Transition to: ${t} (Loop: ${o.loop})`);
+  }
+  onFinished(t) {
+    if (this.currentState && this.activeActions.get(this.currentState) === t.action) {
+      const e = this.states[this.currentState], o = () => {
+        e && e.next ? this.play(e.next) : !e.loop && this.currentState !== this.defaultState && this.play(this.defaultState);
+      };
+      e.holdDuration && e.holdDuration > 0 ? setTimeout(o, e.holdDuration * 1e3) : o();
+    }
+  }
+  /**
+   * Finds an animation clip by name using exact, case-insensitive, or fuzzy matching.
+   */
+  findClip(t) {
+    let e = this.clips.find((o) => o.name === t);
+    return e || (e = this.clips.find((o) => o.name.toLowerCase() === t.toLowerCase())), e || (e = this.clips.find((o) => o.name.toLowerCase().includes(t.toLowerCase()))), e;
+  }
+}
+class L {
+  container;
+  scene;
+  camera;
+  renderer;
+  controls;
+  clock;
+  loader;
+  stageLoader;
+  avatarModel = null;
+  stageModel = null;
+  animController = null;
+  stageAnimController = null;
+  constructor(t) {
+    const e = document.getElementById(t);
+    if (!e) throw new Error(`Container #${t} not found`);
+    this.container = e, this.clock = new i.Clock(), this.loader = new M(), this.stageLoader = new S(), this.scene = new i.Scene(), this.scene.background = new i.Color(1710618), this.scene.fog = new i.Fog(1710618, 10, 50), this.camera = new i.PerspectiveCamera(
+      45,
+      window.innerWidth / window.innerHeight,
+      0.1,
+      100
+    ), this.camera.position.set(0, 1.5, 5), this.renderer = new g({ antialias: !0, alpha: !0 }), this.renderer.setSize(window.innerWidth, window.innerHeight), this.renderer.setPixelRatio(window.devicePixelRatio), this.container.appendChild(this.renderer.domElement), this.setupLights(), this.controls = new y(this.camera, this.renderer.domElement), this.controls.enableDamping = !0, this.controls.target.set(0, 1, 0), window.addEventListener("resize", this.onWindowResize.bind(this)), this.renderer.setAnimationLoop(this.animate.bind(this));
+  }
+  setupLights() {
+    const t = new i.AmbientLight(16777215, 0.6);
+    this.scene.add(t);
+    const e = new i.DirectionalLight(16777215, 1);
+    e.position.set(5, 10, 7), e.castShadow = !0, this.scene.add(e);
+    const o = new i.SpotLight(54015, 5);
+    o.position.set(-5, 5, -5), o.lookAt(0, 1, 0), this.scene.add(o);
+  }
+  /**
+   * Load an avatar by config URL
+   */
+  async loadAvatar(t) {
+    this.avatarModel && this.scene.remove(this.avatarModel);
+    const { model: e, config: o, animations: a } = await this.loader.load(t);
+    if (this.avatarModel = e, this.scene.add(this.avatarModel), a.length > 0) {
+      this.animController = new u(this.avatarModel, a);
+      const n = o.animations || {
+        defaultState: "idle",
+        states: {
+          idle: { clipName: "Idle", loop: !0 },
+          wave: { clipName: "Wave", loop: !1, next: "idle" },
+          dance: { clipName: "Dance", loop: !1, next: "idle" },
+          bow: { clipName: "Bow", loop: !1, next: "idle" },
+          walk: { clipName: "Walking", loop: !0 }
+        }
+      };
+      this.animController.init(n);
+    }
+    console.log(`[Flow] Avatar "${o.name}" loaded successfully.`);
+  }
+  /**
+   * Load a stage (podium/scene) by config URL
+   */
+  async loadStage(t) {
+    this.stageModel && this.scene.remove(this.stageModel);
+    const { model: e, config: o, animations: a } = await this.stageLoader.load(t);
+    this.stageModel = e, this.scene.add(this.stageModel), a.length > 0 && o.animations && (this.stageAnimController = new u(this.stageModel, a), this.stageAnimController.init(o.animations)), console.log(`[Flow] Stage "${o.name}" loaded successfully.`);
+  }
+  onWindowResize() {
+    this.camera.aspect = window.innerWidth / window.innerHeight, this.camera.updateProjectionMatrix(), this.renderer.setSize(window.innerWidth, window.innerHeight);
+  }
+  // State
+  isAutoRotate = !1;
+  /**
+   * Play a specific action
+   */
+  playAction(t) {
+    if (console.log(`[FlowEngine] Playing action: ${t}`), this.animController) {
+      this.animController.play(t.toLowerCase());
+      return;
+    }
+  }
+  animate(t) {
+    const e = this.clock.getDelta();
+    this.avatarModel && this.animController && this.animController.update(e), this.stageModel && this.stageAnimController && this.stageAnimController.update(e), this.controls.autoRotate = this.isAutoRotate, this.controls.update(), this.renderer.render(this.scene, this.camera);
+  }
+}
+export {
+  u as AnimationController,
+  M as AvatarLoader,
+  L as FlowEngine
+};

package/dist/flow.umd.js

@@ -0,0 +1 @@
+(function(l,p){typeof exports=="object"&&typeof module<"u"?p(exports,require("three"),require("three/webgpu"),require("three/examples/jsm/controls/OrbitControls.js"),require("three/examples/jsm/loaders/GLTFLoader.js")):typeof define=="function"&&define.amd?define(["exports","three","three/webgpu","three/examples/jsm/controls/OrbitControls.js","three/examples/jsm/loaders/GLTFLoader.js"],p):(l=typeof globalThis<"u"?globalThis:l||self,p(l.Flow={},l.THREE,l.THREE,l.OrbitControls_js,l.GLTFLoader_js))})(this,(function(l,p,S,C,y){"use strict";function A(d){const t=Object.create(null,{[Symbol.toStringTag]:{value:"Module"}});if(d){for(const e in d)if(e!=="default"){const o=Object.getOwnPropertyDescriptor(d,e);Object.defineProperty(t,e,o.get?o:{enumerable:!0,get:()=>d[e]})}}return t.default=d,Object.freeze(t)}const i=A(p);class M{loader;constructor(){this.loader=new y.GLTFLoader}async load(t){console.log(`[Flow] Loading avatar config from: ${t}`);try{const e=await fetch(t);if(!e.ok)throw new Error(`Failed to load config: ${e.statusText}`);const o=await e.json(),n=t.substring(0,t.lastIndexOf("/")+1)+o.modelSrc;console.log(`[Flow] Config loaded. Loading model from: ${n}`);let r,a=[];try{const c=await this.loader.loadAsync(n);r=c.scene,a=c.animations||[]}catch(c){console.warn(`[Flow] Failed to load 3D model at ${n}. Using fallback placeholder.`,c),r=this.createFallbackAvatar()}return this.applyConfig(r,o),{model:r,config:o,animations:a}}catch(e){throw console.error("[Flow] Error loading avatar:",e),e}}applyConfig(t,e){e.scale&&t.scale.setScalar(e.scale),e.initialPosition&&t.position.set(...e.initialPosition),t.traverse(o=>{o.isMesh&&(o.castShadow=!0,o.receiveShadow=!0)})}createFallbackAvatar(){const t=new i.Group,e=new i.MeshStandardMaterial({color:54015,roughness:.3,metalness:.8}),o=new i.BoxGeometry(.8,.9,.8),s=new i.Mesh(o,e);s.position.y=1.5,s.name="Head",t.add(s);const n=new i.SphereGeometry(.1),r=new i.MeshBasicMaterial({color:16777215}),a=new i.Mesh(n,r);a.position.set(-.2,1.5,.4),t.add(a);const c=new i.Mesh(n,r);c.position.set(.2,1.5,.4),t.add(c);const w=new i.CylinderGeometry(.6,.4,1.5,8),h=new i.Mesh(w,e);h.position.y=.5,h.name="Body",t.add(h);const m=new i.CapsuleGeometry(.15,1),u=new i.Mesh(m,e);u.position.set(-.9,.8,0),u.rotation.z=Math.PI/4,u.name="LeftArm",t.add(u);const f=new i.Mesh(m,e);return f.position.set(.9,.8,0),f.rotation.z=-Math.PI/4,f.name="RightArm",t.add(f),t}}class L{loader;constructor(){this.loader=new y.GLTFLoader}async load(t){try{const e=await fetch(t);if(!e.ok)throw new Error("Failed to load stage config");const o=await e.json();let s,n=[];if(o.modelSrc){const a=t.substring(0,t.lastIndexOf("/")+1)+o.modelSrc,c=await this.loader.loadAsync(a);s=c.scene,n=c.animations||[]}else s=this.createProceduralStage();return this.applyConfig(s,o),{model:s,config:o,animations:n}}catch(e){throw console.error("[Flow] Stage load error:",e),e}}applyConfig(t,e){e.scale&&t.scale.setScalar(e.scale),e.position&&t.position.set(...e.position),e.rotation&&t.rotation.set(...e.rotation),t.traverse(o=>{o.isMesh&&(o.receiveShadow=!0,o.castShadow=!0)})}createProceduralStage(){const t=new i.Group,e=new i.CylinderGeometry(2,2.2,.2,32),o=new i.MeshStandardMaterial({color:2236962,roughness:.2,metalness:.8}),s=new i.Mesh(e,o);s.position.y=-.1,t.add(s);const n=new i.TorusGeometry(1.8,.05,16,100),r=new i.MeshBasicMaterial({color:54015}),a=new i.Mesh(n,r);a.rotation.x=-Math.PI/2,a.position.y=.01,t.add(a);const c=new i.BoxGeometry(.5,.05,.5);for(let w=0;w<4;w++){const h=new i.Mesh(c,o),m=w/4*Math.PI*2;h.position.set(Math.cos(m)*2.5,0,Math.sin(m)*2.5),h.lookAt(0,0,0),t.add(h)}return t}}class g{mixer;clips;states={};activeActions=new Map;currentState=null;defaultState="idle";constructor(t,e){this.mixer=new i.AnimationMixer(t),this.clips=e,this.mixer.addEventListener("finished",this.onFinished.bind(this))}init(t){this.defaultState=t.defaultState,this.states=t.states,Object.entries(this.states).forEach(([e,o])=>{this.findClip(o.clipName)||console.warn(`[AnimationController] Clip "${o.clipName}" for state "${e}" not found.`)}),this.play(this.defaultState)}update(t){this.mixer.update(t)}play(t,e=!1){const o=this.states[t];if(!o){console.warn(`[AnimationController] State "${t}" not defined.`);return}const s=this.findClip(o.clipName);if(!s||this.currentState===t&&!e)return;const n=this.mixer.clipAction(s);n.setLoop(o.loop?i.LoopRepeat:i.LoopOnce,o.loop?1/0:1),n.clampWhenFinished=!o.loop,n.timeScale=o.timeScale??1;const r=o.fadeDuration??.3;if(this.currentState){const a=this.activeActions.get(this.currentState);a&&a!==n?(a.fadeOut(r),n.reset(),n.fadeIn(r),n.play()):n.reset().play()}else n.reset().play();this.activeActions.set(t,n),this.currentState=t,console.log(`[Anim] Transition to: ${t} (Loop: ${o.loop})`)}onFinished(t){if(this.currentState&&this.activeActions.get(this.currentState)===t.action){const e=this.states[this.currentState],o=()=>{e&&e.next?this.play(e.next):!e.loop&&this.currentState!==this.defaultState&&this.play(this.defaultState)};e.holdDuration&&e.holdDuration>0?setTimeout(o,e.holdDuration*1e3):o()}}findClip(t){let e=this.clips.find(o=>o.name===t);return e||(e=this.clips.find(o=>o.name.toLowerCase()===t.toLowerCase())),e||(e=this.clips.find(o=>o.name.toLowerCase().includes(t.toLowerCase()))),e}}class b{container;scene;camera;renderer;controls;clock;loader;stageLoader;avatarModel=null;stageModel=null;animController=null;stageAnimController=null;constructor(t){const e=document.getElementById(t);if(!e)throw new Error(`Container #${t} not found`);this.container=e,this.clock=new i.Clock,this.loader=new M,this.stageLoader=new L,this.scene=new i.Scene,this.scene.background=new i.Color(1710618),this.scene.fog=new i.Fog(1710618,10,50),this.camera=new i.PerspectiveCamera(45,window.innerWidth/window.innerHeight,.1,100),this.camera.position.set(0,1.5,5),this.renderer=new S.WebGPURenderer({antialias:!0,alpha:!0}),this.renderer.setSize(window.innerWidth,window.innerHeight),this.renderer.setPixelRatio(window.devicePixelRatio),this.container.appendChild(this.renderer.domElement),this.setupLights(),this.controls=new C.OrbitControls(this.camera,this.renderer.domElement),this.controls.enableDamping=!0,this.controls.target.set(0,1,0),window.addEventListener("resize",this.onWindowResize.bind(this)),this.renderer.setAnimationLoop(this.animate.bind(this))}setupLights(){const t=new i.AmbientLight(16777215,.6);this.scene.add(t);const e=new i.DirectionalLight(16777215,1);e.position.set(5,10,7),e.castShadow=!0,this.scene.add(e);const o=new i.SpotLight(54015,5);o.position.set(-5,5,-5),o.lookAt(0,1,0),this.scene.add(o)}async loadAvatar(t){this.avatarModel&&this.scene.remove(this.avatarModel);const{model:e,config:o,animations:s}=await this.loader.load(t);if(this.avatarModel=e,this.scene.add(this.avatarModel),s.length>0){this.animController=new g(this.avatarModel,s);const n=o.animations||{defaultState:"idle",states:{idle:{clipName:"Idle",loop:!0},wave:{clipName:"Wave",loop:!1,next:"idle"},dance:{clipName:"Dance",loop:!1,next:"idle"},bow:{clipName:"Bow",loop:!1,next:"idle"},walk:{clipName:"Walking",loop:!0}}};this.animController.init(n)}console.log(`[Flow] Avatar "${o.name}" loaded successfully.`)}async loadStage(t){this.stageModel&&this.scene.remove(this.stageModel);const{model:e,config:o,animations:s}=await this.stageLoader.load(t);this.stageModel=e,this.scene.add(this.stageModel),s.length>0&&o.animations&&(this.stageAnimController=new g(this.stageModel,s),this.stageAnimController.init(o.animations)),console.log(`[Flow] Stage "${o.name}" loaded successfully.`)}onWindowResize(){this.camera.aspect=window.innerWidth/window.innerHeight,this.camera.updateProjectionMatrix(),this.renderer.setSize(window.innerWidth,window.innerHeight)}isAutoRotate=!1;playAction(t){if(console.log(`[FlowEngine] Playing action: ${t}`),this.animController){this.animController.play(t.toLowerCase());return}}animate(t){const e=this.clock.getDelta();this.avatarModel&&this.animController&&this.animController.update(e),this.stageModel&&this.stageAnimController&&this.stageAnimController.update(e),this.controls.autoRotate=this.isAutoRotate,this.controls.update(),this.renderer.render(this.scene,this.camera)}}l.AnimationController=g,l.AvatarLoader=M,l.FlowEngine=b,Object.defineProperty(l,Symbol.toStringTag,{value:"Module"})}));

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { FlowEngine } from './core/FlowEngine';
+export { AvatarLoader } from './core/AvatarLoader';
+export { AnimationController } from './core/AnimationController';
+export type { AvatarConfig, AnimationStateConfig } from './types';

package/dist/types/index.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Avatar Configuration Interface
+ * 定义数字人的元数据结构，对应资源包中的 config.json
+ */
+export interface AvatarConfig {
+    name: string;
+    modelSrc: string;
+    scale?: number;
+    initialPosition?: [number, number, number];
+    /** Animation State Machine Configuration */
+    animations?: {
+        defaultState: string;
+        states: Record<string, AnimationStateConfig>;
+    };
+}
+export interface AnimationStateConfig {
+    /** The exact name of the clip in the GLB (fuzzy matching supported if not found) */
+    clipName: string;
+    /** Whether the animation should loop */
+    loop?: boolean;
+    /** The state to transition to after this one finishes (for non-looping) */
+    next?: string;
+    /** Cross-fade duration in seconds (default: 0.3) */
+    fadeDuration?: number;
+    /** Time scale (speed), default 1.0 */
+    timeScale?: number;
+    /** Duration to hold the last frame before transitioning (seconds) */
+    holdDuration?: number;
+}
+export interface StageConfig {
+    name: string;
+    modelSrc?: string;
+    scale?: number;
+    position?: [number, number, number];
+    rotation?: [number, number, number];
+    /** Animation logic for the stage (e.g. rotating, rising) */
+    animations?: {
+        defaultState: string;
+        states: Record<string, AnimationStateConfig>;
+    };
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@guoquan.net/flow-engine",
+  "version": "0.1.2",
+  "description": "A high-performance, WebGPU-based digital human engine.",
+  "type": "module",
+  "main": "./dist/flow.umd.js",
+  "module": "./dist/flow.es.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc && vite build",
+    "build:demo": "tsc && cross-env BUILD_DEMO=true vite build",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "preview": "vite preview",
+    "prepare": "npm run build"
+  },
+  "peerDependencies": {
+    "three": ">=0.170.0"
+  },
+  "devDependencies": {
+    "@codecov/vite-plugin": "^1.9.1",
+    "@types/node": "^25.0.3",
+    "@types/three": "^0.182.0",
+    "@vitest/coverage-v8": "^4.0.16",
+    "cross-env": "^10.1.0",
+    "jsdom": "^27.4.0",
+    "three": "^0.182.0",
+    "typescript": "~5.9.3",
+    "vite": "^7.2.4",
+    "vite-plugin-dts": "^4.5.4",
+    "vitest": "^4.0.16"
+  }
+}