@vyr/engine 0.0.33 → 0.0.34

package/src/descriptor/HTML.ts

@@ -0,0 +1,22 @@
+import { Descriptor } from "./Descriptor"
+import { HtmlAttributes } from "../schema";
+
+/**
+ * HTML接口
+ * 表示HTML元素，用于在二维场景中显示HTML内容
+ * 
+ * 作用：作为二维界面元素的接口，提供了HTML元素的基础属性
+ */
+export interface HTML extends Descriptor {
+
+    /**是否为HTML节点 */
+    isHTML: true
+
+    /**
+     * 是否可见
+     * @default true
+     */
+    visible: boolean
+
+    htmlAttributes: HtmlAttributes
+}

package/src/descriptor/HTMLService.ts

@@ -0,0 +1,42 @@
+import { DeserializationObject } from "../Serialization"
+import { HtmlAttributes, HtmlAttributesSchema } from "../schema"
+import { Service } from "./Service"
+import { Descriptor } from "./Descriptor"
+import { registerService } from "../utils/Service"
+
+/**
+ * 二维（HTML）场景渲染服务
+ * 
+ * 作用：负责管理二维节点（如Div、ELButton等）的渲染。必须作为Scene的直接子节点挂载，
+ * 否则所有二维节点将无法正常渲染。
+ * 
+ * 使用要求：
+ * 1. 必须添加为Scene的子节点
+ * 2. 在场景中仅需一个实例
+ * 3. 应在其他二维节点之前初始化
+ * 
+ * @example
+ * // 场景结构示例
+ * Scene
+ * └── HtmlSceneService  // 必须在此位置
+ *     └── Div          // 依赖此服务才能渲染
+ */
+export class HTMLService extends Descriptor implements Service {
+    /**类类型标识 */
+    static type = 'HTMLService'
+
+    readonly isHTML = true
+
+    visible: boolean
+
+    htmlAttributes: HtmlAttributes
+
+    constructor(descriptor: Partial<DeserializationObject<HTMLService>> = {}) {
+        super(descriptor)
+        this.visible = descriptor.visible ?? true
+        this.htmlAttributes = HtmlAttributesSchema.parse(descriptor.htmlAttributes)
+    }
+}
+
+Descriptor.register(HTMLService)
+registerService(HTMLService.type)

package/src/descriptor/HTMLTransformController.ts

@@ -0,0 +1,67 @@
+import { DeserializationObject } from "../Serialization"
+import { Descriptor } from "./Descriptor"
+import { Controller } from "./Controller"
+
+/**
+ * HTML变换控制器类
+ * 用于控制HTML元素的变换操作
+ * 
+ * 作用：提供对HTML元素的变换控制功能，如移动、缩放、旋转等操作
+ * 支持通过摄像机和目标元素进行交互控制
+ */
+export class HTMLTransformController extends Descriptor implements Controller {
+    /**类类型标识 */
+    static type = 'HTMLTransformController'
+
+    /**
+     * 控制器是否启用
+     * @default false
+     */
+    enabled: boolean
+
+    /**
+     * 控制器的摄像机
+     * 指定用于交互控制的摄像机UUID
+     * @default ""
+     */
+    camera: string
+
+    /**
+     * 控制器的模式
+     * 定义控制器的操作模式
+     * @default ""
+     */
+    mode: string
+
+    /**
+     * 控制器的目标
+     * 指定要控制的目标元素UUID
+     * @default ""
+     */
+    target: string
+
+    /**
+     * 控制器触发事件时执行的脚本依赖
+     * 指定事件触发时要执行的脚本
+     * @default ""
+     */
+    event: string
+
+    /**
+     * 高亮目标
+     * 指定要高亮显示的元素UUID
+     * @default ""
+     */
+    highlight: string
+
+    constructor(descriptor: Partial<DeserializationObject<HTMLTransformController>> = {}) {
+        super(descriptor)
+        this.enabled = descriptor.enabled ?? false
+        this.camera = descriptor.camera ?? ''
+        this.mode = descriptor.mode ?? ''
+        this.target = descriptor.target ?? ''
+        this.event = descriptor.event ?? ''
+        this.highlight = descriptor.highlight ?? ''
+    }
+}
+Descriptor.register(HTMLTransformController)

package/src/descriptor/Input.ts

@@ -0,0 +1,29 @@
+import { DeserializationObject } from "../Serialization"
+import { HtmlAttributes, HtmlAttributesSchema } from "../schema"
+import { Descriptor } from "./Descriptor"
+import { HTML } from "./HTML"
+
+/**
+ * Input类
+ * 表示一个HTML input元素，用于在二维场景中接收用户输入
+ * 
+ * 作用：作为二维界面的输入控件，支持文本输入、密码输入等多种输入类型
+ * 继承自HTML类，拥有HTML元素的所有样式和布局属性
+ */
+export class Input extends Descriptor implements HTML {
+  /**类类型标识 */
+  static type = 'Input'
+
+  readonly isHTML = true
+
+  visible: boolean
+
+  htmlAttributes: HtmlAttributes
+
+  constructor(descriptor: Partial<DeserializationObject<Input>> = {}) {
+    super(descriptor)
+    this.visible = descriptor.visible ?? true
+    this.htmlAttributes = HtmlAttributesSchema.parse(descriptor.htmlAttributes)
+  }
+}
+Descriptor.register(Input)

package/src/descriptor/Interaction.ts

@@ -0,0 +1,80 @@
+import { DeserializationObject, Serialization } from "../Serialization";
+import { Descriptor } from "./Descriptor";
+import { Graphics } from "../graphics";
+import { Executor } from "../Executor";
+import { InteractionMapper, InteractionNode, InteractionNodeInputCollection, InteractionNodeArraySchame, InteractionNodeArray } from "../schema";
+
+const privateState = {
+    executorPool: new WeakMap<Descriptor, Executor>()
+}
+
+/**
+ * 交互类
+ * 派生自Descriptor，用于定义和管理交互流程
+ * 
+ * 作用：作为交互系统的核心类，用于组织和执行交互节点，控制交互流程的执行顺序
+ */
+export class Interaction extends Descriptor {
+    /** 类类型标识 */
+    static type = 'Interaction'
+    /** 交互的所有根节点集合（每个连线的第一个节点） */
+    roots: string[]
+    /** 交互的所有节点 */
+    nodes: InteractionNodeArray
+    /** 交互节点的执行顺序（连线顺序，source表示左侧，target表示右侧，从左到右） */
+    mappers: InteractionMapper[]
+
+    constructor(descriptor: Partial<DeserializationObject<Interaction>> = {}) {
+        super(descriptor)
+        this.roots = descriptor.roots ? Serialization.deepClone(descriptor.roots) : []
+        this.nodes = InteractionNodeArraySchame.parse(descriptor.nodes)
+        this.mappers = descriptor.mappers ? Serialization.deepClone(descriptor.mappers) : []
+    }
+
+    /**
+     * 添加节点到交互中
+     * 同时自动创建节点之间的映射关系
+     * @param nodes 要添加的节点数组
+     */
+    addNode(nodes: InteractionNode[]) {
+        const count = nodes.length
+        const max = count - 1
+        for (let i = 0; i < count; i++) {
+            const node = nodes[i]
+            this.nodes.push(node)
+            if (i < max) {
+                this.mappers.push({ source: node.id, target: nodes[i + 1].id })
+            }
+        }
+    }
+
+    /**
+     * 执行交互
+     * @param nodes 交互节点集合
+     * @param graphics 图形对象
+     * @param trigger 触发条件
+     * @param otherArgs 其他参数
+     */
+    async execute(nodes: InteractionNodeInputCollection, graphics: Graphics, trigger: string, otherArgs?: { [k: string]: any }) {
+        let executor = privateState.executorPool.get(this)
+        if (executor === undefined) {
+            executor = new Executor()
+            executor.update(this)
+            privateState.executorPool.set(this, executor)
+        }
+        await executor.execute(nodes, this, graphics, trigger, otherArgs)
+    }
+
+    /**
+     * 设置需要更新
+     * 当交互配置发生变化时调用，更新执行器
+     */
+    setNeedsUpdate() {
+        const executor = privateState.executorPool.get(this)
+        if (executor === undefined) return
+        executor.update(this)
+    }
+}
+
+Descriptor.register(Interaction)
+

package/src/descriptor/Node.ts

@@ -0,0 +1,98 @@
+import { Euler, Vector3 } from "../math"
+import { DeserializationObject } from "../Serialization"
+import { Descriptor } from "./Descriptor"
+
+/**
+ * 节点类
+ * 3D场景的基础容器节点，用于组织和管理三维空间中的对象层次结构。
+ * 
+ * 主要作用：
+ * 1. 作为3D场景的逻辑容器，用于对子节点进行分组和管理
+ * 2. 提供统一的变换（位置、旋转、缩放）继承体系
+ * 3. 控制渲染状态（可见性、渲染顺序、阴影设置等）
+ * 4. 通过层级系统实现对象的分组和过滤
+ * 
+ * 特性说明：
+ * - 此类是纯容器节点，本身不包含任何可渲染的几何体或材质
+ * - 所有变换属性（position、rotation、scale）将传递给子节点
+ * - 通过 layer 属性支持场景对象的分层管理和选择性渲染
+ * - 通过 renderOrder 属性控制同级节点的渲染顺序
+ * - 通过 visible 属性可控制节点及其所有子节点的可见性
+ * - 通过 castShadow/receiveShadow 控制阴影投射和接收行为（影响子节点）
+ * 
+ * 注意：此节点类型仅作为组织和管理用途，不会在渲染管线中产生任何绘制调用。
+ * 若需要显示几何体，请使用 Mesh 或其它可渲染节点类型。
+ */
+export class Node extends Descriptor {
+    /**类类型标识 */
+    static type = 'Node'
+
+    /**
+     * 缩放向量
+     * 控制节点在三维空间中的缩放比例
+     * @default {x:1,y:1,z:1}
+     */
+    readonly scale: Vector3
+
+    /**
+     * 位置向量
+     * 控制节点在三维空间中的位置坐标
+     * @default {x:0,y:0,z:0}
+     */
+    readonly position: Vector3
+
+    /**
+     * 旋转欧拉角
+     * 控制节点在三维空间中的旋转状态
+     * @default {x:0,y:0,z:0,order:'XYZ'}
+     */
+    readonly rotation: Euler
+
+    /**
+     * 节点层级
+     * 用于节点的分层管理和渲染过滤
+     * @default 0
+     */
+    layer: number
+
+    /**
+     * 是否可见
+     * 控制节点是否在场景中可见
+     * @default true
+     */
+    visible: boolean
+
+    /**
+     * 渲染顺序
+     * 控制节点的渲染先后顺序
+     * @default 0
+     */
+    renderOrder: number
+
+    /**
+     * 是否投射阴影
+     * 控制节点是否向场景中投射阴影
+     * @default false
+     */
+    castShadow: boolean
+
+    /**
+     * 是否接收阴影
+     * 控制节点是否接收来自其他物体的阴影
+     * @default false
+     */
+    receiveShadow: boolean
+
+    constructor(descriptor: Partial<DeserializationObject<Node>> = {}) {
+        super(descriptor)
+        this.scale = descriptor.scale ? Vector3.create(descriptor.scale) : Vector3.create(1, 1, 1)
+        this.position = Vector3.create(descriptor.position)
+        this.rotation = Euler.create(descriptor.rotation)
+        this.layer = descriptor.layer ?? 0
+        this.visible = descriptor.visible ?? true
+        this.renderOrder = descriptor.renderOrder ?? 0
+        this.castShadow = descriptor.castShadow ?? false
+        this.receiveShadow = descriptor.receiveShadow ?? false
+    }
+}
+Descriptor.register(Node)

package/src/descriptor/Scene.ts

@@ -0,0 +1,110 @@
+import { Vector2, Vector3 } from "../math";
+import { SharedCSSStyle } from "../schema";
+import { DeserializationObject } from "../Serialization"
+import { Descriptor } from "./Descriptor"
+import { Service } from "./Service";
+
+/**
+ * 射线 intersection接口
+ * 定义了射线与对象相交的信息
+ */
+export interface RayIntersection {
+  object: Descriptor
+  distance: number
+  point: Vector3
+  normal: Vector2 | null
+  uv: Vector2 | null
+  uv1: Vector2 | null
+  faceIndex: number | null
+  instanceId: number | null
+}
+
+/**
+ * Scene类
+ * 场景类，作为场景资产的根节点，负责管理和调度场景中的所有服务节点
+ * 
+ * 作用：
+ * 1. 作为服务节点的容器，管理子服务节点的生命周期
+ * 2. 提供全局样式注册和管理功能，支持场景级别的样式定义
+ * 
+ * @example
+ * // 场景结构示例
+ * Scene
+ * └── HtmlSceneService  // 服务节点
+ *     └── Div          // 依赖此服务才能渲染
+ * └── Scene3DService  // 服务节点
+ *     └── Mesh          // 依赖此服务才能渲染
+ */
+export class Scene extends Descriptor {
+  /**类类型标识，用于运行时类型识别 */
+  static type = 'Scene'
+
+  /**
+   * 全局样式存储Map
+   * 键：CSS选择器字符串
+   * 值：CSS属性键值对对象
+   * 作用：集中管理场景中所有全局样式定义
+   */
+  static globalStyle = new Map<string, any>
+
+  /**
+   * 注册全局样式
+   * 将CSS样式注册到全局样式表中
+   * @param selector - CSS选择器，如'.button', '#header'
+   * @param cssContent - CSS属性对象，如{ color: 'red', fontSize: '14px' }
+   */
+  static registerGlobalStyle = (selector: string, cssContent: any) => {
+    this.globalStyle.set(selector, cssContent)
+  }
+
+  /**
+   * 生成全局样式字符串
+   * 将注册的所有全局样式转换为CSS字符串格式
+   * @returns 格式化的CSS样式字符串，可直接嵌入style标签
+   */
+  static useGlobalStyle = () => {
+    const entries = this.globalStyle.entries()
+
+    let cssContent = ''
+    for (const [selector, content] of entries) {
+      const keys = Object.keys(content)
+      let style = `${selector} {\n`
+      for (const key of keys) {
+        style += `${key}:${content[key]};\n`
+      }
+      style += '}\n\n'
+      cssContent += style
+    }
+
+    return cssContent
+  }
+
+  /**
+   * 子服务节点数组
+   * 声明并约束children必须为Service类型的数组
+   * 场景作为服务调度器，其直接子节点只能是服务节点
+   */
+  declare children: Service[]
+
+  /**
+   * 场景渲染相机标识
+   * 指定用于渲染当前场景的相机UUID
+   * 空字符串表示使用默认相机
+   * @default ""
+   */
+  camera: string
+
+  /**
+   * 共享CSS样式对象
+   * 包含类名样式和动画定义，可在场景内的服务节点间共享
+   * 用于实现样式复用和统一管理
+   */
+  sharedCSSStyle: SharedCSSStyle
+
+  constructor(descriptor: Partial<DeserializationObject> = {}) {
+    super(descriptor)
+    this.camera = descriptor.camera ?? ''
+    this.sharedCSSStyle = descriptor.sharedCSSStyle ? Descriptor.deepClone(descriptor.sharedCSSStyle) : { classNames: {}, animations: {} }
+  }
+}
+Descriptor.register(Scene)

package/src/descriptor/Service.ts

@@ -0,0 +1,11 @@
+import { HTML } from "./HTML"
+
+/**
+ * 服务接口声明，定义了服务类的通用结构和行为。
+ * 
+ * 说明：
+ * 1. 所有具体服务类都应实现此接口
+ */
+export interface Service extends HTML {
+
+}

package/src/descriptor/Store.ts

@@ -0,0 +1,136 @@
+import { StoreData, StoreDataSchema } from "../schema";
+import { Asset } from "../asset";
+import { observer } from "../graphics/Observer";
+import { DeserializationObject } from "../Serialization";
+import { Descriptor } from "./Descriptor";
+
+export interface Data {
+    [k: string]: any
+}
+
+/**
+ * 数据容器类
+ * 用于管理和操作结构化数据集合
+ * 
+ * 作用：作为数据存储和获取的统一接口，提供数据缓存、数据更新通知等功能
+ * 注意：该类仅负责数据存储和管理，不涉及视图渲染
+ * 
+ * 典型应用：
+ * - 为图表、列表、表单等组件提供动态数据支持
+ * - 在交互节点中动态更新数据集，实现数据驱动的流程控制
+ * - 作为多个组件间的共享数据源，支持状态同步
+ * 
+ * 与组件集成：通过变量映射机制实现响应式数据绑定
+ * ```json
+ * {
+ *   "uuid": "div-instance-uuid",
+ *   "type": "Div",
+ *   "store": "/static:/assets/data/profile.store.json",
+ *   "variables": {
+ *     "name": { "type": "key", "enabled": true, "value": "name" },
+ *     "bgColor": { "type": "key", "enabled": true, "value": "style.htmlAttributes.backgroundColor" },
+ *     "items": { "type": "key", "enabled": true, "value": "items" }
+ *   }
+ * }
+ * ```
+ * 
+ * 对应的数据集资产：
+ * ```json
+ * {
+ *   "uuid": "store-profile-uuid",
+ *   "type": "Store",
+ *   "name": "用户资料数据集",
+ *   "data": {
+ *     "name": "张三",
+ *     "bgColor": "#00ff00",
+ *     "items": ["选项1", "选项2", "选项3"]
+ *   }
+ * }
+ * ```
+ * 
+ * 交互系统集成：支持作为数据源或目标
+ * 
+ * 1. 数据集获取节点
+ * ```json
+ * {
+ *   "id": "exec-find-store",
+ *   "type": "Execute",
+ *   "script": "find",
+ *   "input": {
+ *     "target": "store-uuid",
+ *   }
+ * }
+ * ```
+ * 
+ * 2. 数据更新节点：
+ * ```json
+ * {
+ *   "id": "exec-update-store",
+ *   "type": "Execute",
+ *   "script": "update",
+ *   "input": {
+ *     "target": "exec-find-store",
+ *     "value": { "data": { "name": "李四", "bgColor": "#ff0000" } },
+ *     "nodeIds":""
+ *   }
+ * }
+ * ```
+ * 
+ * 数据流动机制：
+ * ```
+ * 交互节点更新 → 依赖组件收到通知 → 重新读取数据 → 变量映射更新 → 重绘组件
+ * ```
+ * 
+ * 使用场景：
+ * - UI数据源：为Div、图表、列表等提供动态数据
+ * - 表单/列表管理：存储和管理数据集合
+ * - 状态管理：作为全局或局部状态容器，支持多组件状态同步
+ * 
+ * 最佳实践：
+ * - 命名应具业务语义，便于识别
+ * - 数据设计建议扁平化，避免过深嵌套
+ * - 频繁更新的字段可拆分独立数据集，减少通知开销
+ * - 组件只映射所需字段，避免不必要依赖
+ * - UUID全局唯一，便于精确定位
+ */
+export class Store extends Descriptor {
+    /**类类型标识 */
+    static type = 'Store'
+
+    static getData<T = Data>(store: string) {
+        const descriptor = Asset.get(store)
+        if (descriptor instanceof Store) {
+            return descriptor.data as T
+        } else {
+            return null
+        }
+    }
+
+    static getCollection<T = Data>(store: string): T[] {
+        const data = this.getData<T>(store)
+
+        if (data === null) return []
+
+        return Array.isArray(data) ? data : [data]
+    }
+
+    /**
+     * 数据
+     * @default {}
+     */
+    data: StoreData
+
+    constructor(descriptor: Partial<DeserializationObject<Store>> = {}) {
+        super(descriptor)
+        this.data = StoreDataSchema.parse(descriptor.data)
+    }
+
+    /**
+     * 设置需要更新
+     */
+    setNeedsUpdate() {
+        observer.trigger('updateDeps', { self: this.uuid })
+    }
+}
+
+Descriptor.register(Store)

package/src/descriptor/Text.ts

@@ -0,0 +1,36 @@
+import { DeserializationObject } from "../Serialization"
+import { HtmlAttributes, HtmlAttributesSchema } from "../schema"
+import { Descriptor } from "./Descriptor"
+import { HTML } from "./HTML"
+
+/**
+ * Text类
+ * 表示一个HTML文本元素，用于在二维场景中显示文本内容
+ * 
+ * 作用：作为二维界面的文本显示控件，支持文本内容的展示
+ * 继承自HTML类，拥有HTML元素的所有样式和布局属性
+ */
+export class Text extends Descriptor implements HTML {
+  /**类类型标识 */
+  static type = 'Text'
+
+  readonly isHTML = true
+
+  visible: boolean
+
+  htmlAttributes: HtmlAttributes
+
+  /**
+   * 文本内容
+   * @default ""
+   */
+  content: string
+
+  constructor(descriptor: Partial<DeserializationObject<Text>> = {}) {
+    super(descriptor)
+    this.visible = descriptor.visible ?? true
+    this.htmlAttributes = HtmlAttributesSchema.parse(descriptor.htmlAttributes)
+    this.content = descriptor.content ?? ''
+  }
+}
+Descriptor.register(Text)

package/src/descriptor/index.ts

@@ -1,16 +1,15 @@
 export * from './Descriptor'
-export * from './DatasetDescriptor'
-export * from './StyleDescriptor'
-export * from './PrefabDescriptor'
-export * from './PrefabInstanceDescriptor'
-export * from './DynamicDescriptor'
-export * from './HTMLDescriptor'
-export * from './DivDescriptor'
-export * from './NodeDescriptor'
-export * from './CameraDescriptor'
-export * from './AnimationUnitDescriptor'
-export * from './ControllerDescriptor'
-export * from './HTMLTransformControllerDescriptor'
-export * from './ServiceDescriptor'
-export * from './HTMLServiceDescriptor'
-export * from './ServiceSchedulerDescriptor'
+export * from './Interaction'
+export * from './Store'
+export * from './HTML'
+export * from './Div'
+export * from './Input'
+export * from './Text'
+export * from './Node'
+export * from './Camera'
+export * from './AnimationUnit'
+export * from './Controller'
+export * from './HTMLTransformController'
+export * from './Service'
+export * from './HTMLService'
+export * from './Scene'

package/src/graphics/Collection.ts

@@ -1,6 +1,6 @@
 import { Unit } from "./Unit"
 
-class UnitCollection {
+export class UnitCollection {
     private readonly instanceCollection = new Map<string, Unit>()
 
     set(unit: Unit) {
@@ -18,8 +18,4 @@ class UnitCollection {
     values() {
         return [...this.instanceCollection.values()]
     }
-}
-
-export {
-    UnitCollection
 }