@vyr/engine 0.0.33 → 0.0.34

package/src/asset/AssetGraph.ts

@@ -4,41 +4,35 @@ import { ArrayUtils } from "../ArrayUtils"
 import { ObjectPool } from "../ObjectPool";
 import { Descriptor } from "../descriptor";
 
-interface Edge {
+export interface Edge {
     key: string
     asset: string
     category: string
 }
 
-interface Port {
+export interface Port {
     descriptor: string
     edges: Edge[]
 }
 
-interface Cell {
+export type Provider<T extends Descriptor = Descriptor> = (descriptor: T, port: Port) => void
+
+export interface Cell {
     url: string
     uuid: string
     ports: Port[]
 }
 
-interface UrlCell {
+export interface UrlCell {
     url: string
     cells: Cell[]
 }
 
-type Provider<T extends Descriptor = Descriptor> = (descriptor: T, port: Port) => void
-
-const privateState = {
-    providerCollection: new Map<string, Provider>(),
-}
-
-class Dependencide {
+export class Dependencide {
     all: string[] = []
     descriptor: string[] = []
+    store: string[] = []
     interaction: string[] = []
-    prefab: string[] = []
-    dataset: string[] = []
-    style: string[] = []
     texture: string[] = []
     material: string[] = []
     geometry: string[] = []
@@ -46,14 +40,16 @@ class Dependencide {
     add(type: keyof Dependencide, url: string) {
         const collection = this[type] as string[]
         if (collection === undefined) return console.warn(type, url)
+        if(Array.isArray(url)){
+            console.log(url)
+        }
         collection.push(url)
         this.descriptor.push(url)
     }
 
     forEachForGraphics(cb: (url: string) => void) {
-        //Graphics遍历资产时，跳过 interaction prefab
-        for (const url of this.dataset) cb(url)
-        for (const url of this.style) cb(url)
+        //Graphics遍历资产时，跳过 interaction
+        for (const url of this.store) cb(url)
         for (const url of this.texture) cb(url)
         for (const url of this.material) cb(url)
         for (const url of this.geometry) cb(url)
@@ -62,9 +58,7 @@ class Dependencide {
     clear() {
         this.all.length = 0
         this.descriptor.length = 0
-        this.prefab.length = 0
-        this.dataset.length = 0
-        this.style.length = 0
+        this.store.length = 0
         this.interaction.length = 0
         this.texture.length = 0
         this.material.length = 0
@@ -73,12 +67,13 @@ class Dependencide {
 }
 
 /**资产关系图，表示资产和资产之间的依赖关系 */
-class AssetGraph {
+export class AssetGraph {
+    private static collection = new Map<string, Provider>()
 
-    private static build(descriptor: Descriptor, port: Port) {
+    static build(descriptor: Descriptor, port: Port) {
         let Prototype = descriptor.constructor as typeof Descriptor
         while (Prototype.prototype instanceof ObjectPool) {
-            const provider = privateState.providerCollection.get(Prototype.type)
+            const provider = this.collection.get(Prototype.type)
             Prototype = Object.getPrototypeOf(Prototype)
             if (provider === undefined) continue
             provider(descriptor, port)
@@ -86,7 +81,7 @@ class AssetGraph {
     }
 
     static register<T extends Descriptor = Descriptor>(type: string, provider: Provider<T>) {
-        privateState.providerCollection.set(type, provider as Provider)
+        this.collection.set(type, provider as Provider)
     }
 
     static get(descriptor: Descriptor, ports: Port[] = []) {
@@ -191,7 +186,7 @@ class AssetGraph {
         if (ports.length === 0) return dependencide
         for (const port of ports) {
             for (const edge of port.edges) {
-                const isDescriptor = Category.isDescriptor(edge.category, 'category')
+                const isDescriptor = Category.isDescriptor(edge.category)
                 this.collection(edge.asset, dependencide, isDescriptor, edge.category as keyof Dependencide)
             }
         }
@@ -241,6 +236,4 @@ class AssetGraph {
 
         return false
     }
-}
-
-export { Edge, Port, Cell, UrlCell, Dependencide, AssetGraph }
+}

package/src/descriptor/AnimationUnit.ts

@@ -0,0 +1,81 @@
+import { AnimationFrameData, parseFrameData, Vector2FrameDataSchema } from "../schema"
+import { DeserializationObject } from "../Serialization"
+import { Descriptor } from "./Descriptor"
+
+/**
+ * 动画单元类
+ * 用于定义和控制单个动画的参数和行为
+ * 
+ * 作用：表示一个独立的动画片段，包含动画的播放状态、持续时间、循环设置、目标属性路径和关键帧数据
+ * 可用于控制场景中对象的各种属性动画，如位置、旋转、缩放、颜色等
+ */
+export class AnimationUnit extends Descriptor {
+    /**类类型标识 */
+    static type = 'AnimationUnit'
+
+    /**
+     * 是否播放动画
+     * 控制动画的启动和暂停状态
+     * @default false
+     */
+    play: boolean
+
+    /**
+     * 动画持续时间（秒）
+     * 定义动画从开始到结束的总时长
+     * @default 0
+     */
+    duration: number
+
+    /**
+     * 循环次数
+     * 定义动画重复播放的次数，Infinity表示无限循环
+     * @default Infinity
+     */
+    count: number
+
+    /**
+     * 循环模式
+     * - 1 顺序循环：动画播放完成后从头开始
+     * - 2 往返循环：动画播放完成后反向播放
+     * @default 1
+     */
+    mode: number
+
+    /**
+     * 动画开始时间（秒）
+     * 定义动画在何时开始播放
+     * @default 0
+     */
+    startTime: number
+
+    /**
+     * 动画目标属性路径
+     * 指向要进行动画的对象属性路径
+     * @default ""
+     */
+    propertyPath: string
+
+    /**
+     * 动画帧数据
+     * 包含动画的关键帧信息，定义了动画的起始值和结束值
+     */
+    frameData: AnimationFrameData
+
+    constructor(descriptor: Partial<DeserializationObject<AnimationUnit>> = {}) {
+        super(descriptor)
+        this.play = descriptor.play ?? false
+        this.duration = descriptor.duration ?? 0
+        this.count = descriptor.count ?? Infinity
+        this.mode = descriptor.mode ?? 1
+        this.startTime = descriptor.startTime ?? 0
+        this.propertyPath = descriptor.propertyPath ?? ''
+        this.frameData = descriptor.frameData ? parseFrameData(descriptor.frameData) : Vector2FrameDataSchema.parse({})
+    }
+}
+
+Descriptor.register(AnimationUnit)
+
+export type {
+    AnimationFrameData
+}

package/src/descriptor/Camera.ts

@@ -0,0 +1,12 @@
+import { Node } from "./Node"
+
+/**
+ * 相机接口
+ * 继承自Node，用于定义场景中的相机对象
+ * 
+ * 作用：相机负责定义场景的观察视角和投影方式
+ * 提供场景渲染时的视角控制
+ */
+export interface Camera extends Node {
+
+}

package/src/descriptor/Controller.ts

@@ -0,0 +1,6 @@
+import { Descriptor } from "./Descriptor"
+
+export interface Controller extends Descriptor {
+
+    enabled: boolean
+}

package/src/descriptor/Descriptor.ts

@@ -1,76 +1,25 @@
 import { language } from '../locale'
+import { DescriptorAdjacency, DescriptorAncestor, DescriptorVariables, DescriptorVariablesSchema, InteractionPropertyArray, InteractionPropertyArraySchame } from '../schema'
 import { listenInstance, ObjectPool } from '../ObjectPool'
-import { ArrayUtils } from '../ArrayUtils'
 import { Generate } from '../Generate'
 import { Traverser } from '../Traverser'
 import { ObjectUtils } from '../ObjectUtils'
 import { DeserializationObject, Serialization, SerializationObject } from '../Serialization'
-import { InteractionPropertyCollection } from '../interaction'
 import { observer } from '../graphics/Observer'
 
-/**描述器祖先节点 */
-interface DescriptorAncestor<T extends Descriptor = Descriptor> {
-    parent: T | null,
-    uuids: string[]
-    collection: Descriptor[]
-}
-
-/**当前描述器节点的邻接关系 */
-interface DescriptorAdjacency {
-    /**当前节点的父节点 */
-    parent: string
-    /**当前节点的前一个节点 */
-    prev: string
-    /**当前节点的后一个节点 */
-    next: string
-}
-
-interface DescriptorPrefab {
-    root: string
-    uuid: string
-}
-
-interface VariabConfig {
-    type: 'key' | 'custom'
-    enabled: boolean
-    value: string
-}
-
-interface DescriptorVariables {
-    [k: string]: VariabConfig
-}
-
 const privateState = {
     classCollection: new Map<string, typeof Descriptor>(),
-    prefabToInstanceCollection: new Map<string, string[]>(),
-    instanceToPrefabCollection: new Map<string, string>(),
     refGraph: new Map<string, string>(),
     getParent: <T extends Descriptor = Descriptor>(uuid: string) => {
         const parent = privateState.refGraph.get(uuid)
         if (parent === undefined) return null
         return Descriptor.get<T>(parent)
     },
-    setPrefabInstance(instance: Descriptor) {
-        if (instance.prefab === false) return
-
-        let instanceCollection = this.prefabToInstanceCollection.get(instance.prefab.uuid)
-        if (instanceCollection === undefined) {
-            instanceCollection = []
-            this.prefabToInstanceCollection.set(instance.prefab.uuid, instanceCollection)
-        }
-
-        ArrayUtils.insert(instanceCollection, instance.uuid)
-        this.instanceToPrefabCollection.set(instance.uuid, instance.prefab.uuid)
-    },
     markclone: (descriptor: Descriptor, root: string, map: Map<string, Descriptor>, childs: Descriptor[]) => {
         const clone = descriptor.clone(false)
         map.set(descriptor.uuid, clone)
         if (clone.interactions.length > 0) childs.push(clone)
 
-        if (clone.prefab === false) {
-            clone.prefab = { root, uuid: descriptor.uuid }
-        }
-
         for (const sub of descriptor.children) {
             const child = privateState.markclone(sub, root, map, childs)
             clone.add(child)
@@ -80,7 +29,6 @@ const privateState = {
     }
 }
 
-
 /**
  * 描述引擎所使用的场景、资产对象
  * 
@@ -90,44 +38,72 @@ const privateState = {
  * 
  * 不建议将一个描述器作为另一个描述器的属性，若要保持引用关系，将描述器的uuid作为属性即可
  */
-class Descriptor extends ObjectPool {
+export class Descriptor extends ObjectPool {
+    /**类类型标识 */
     static type = 'Descriptor'
-    /**注册描述器的派生类 */
+    /**
+     * 注册描述器的派生类
+     * @param DerivedClass 派生类
+     */
     static register(DerivedClass: typeof Descriptor) {
         privateState.classCollection.set(DerivedClass.type, DerivedClass)
     }
-    /**获取注册的派生类 */
+    /**
+     * 获取注册的派生类
+     * @param type 类类型标识
+     * @returns 注册的派生类，如果不存在返回null
+     */
     static getClass<T extends typeof Descriptor>(type: string) {
         return (privateState.classCollection.get(type) ?? null) as T | null
     }
-    /**使用数据动态的创建描述器 */
+    /**
+     * 使用数据动态的创建描述器
+     * @param descriptor 描述器配置对象
+     * @returns 创建的描述器实例
+     */
     static create<T extends Descriptor = Descriptor>(descriptor: Partial<DeserializationObject<Descriptor>>) {
         const Class = this.getClass(descriptor.type ?? Descriptor.type)
         if (Class === null) throw new Error(language.get('descriptor.notRegister', { type: descriptor.type }))
         return new Class(descriptor) as T
     }
-    /**将对象序列化成json字符 */
+    /**
+     * 将对象序列化成json字符
+     * @param descriptor 要序列化的对象
+     * @returns 序列化后的json字符串
+     */
     static serialization(descriptor: SerializationObject) {
         return Serialization.stringify(descriptor)
     }
-    /**将json字符反序列化成对象 */
+    /**
+     * 将json字符反序列化成对象
+     * @param str 要反序列化的json字符串
+     * @returns 反序列化后的对象
+     */
     static deserialization<T = any>(str: string) {
         return Serialization.parse(str) as T
     }
-    /**深度克隆传入的JSON对象 */
-    static deepClone<T = any>(descriptor: SerializationObject) {
+    /**
+     * 深度克隆传入的JSON对象
+     * @param descriptor 要克隆的对象
+     * @returns 克隆后的对象
+     */
+    static deepClone<T extends any = any>(descriptor: SerializationObject) {
         return Serialization.deepClone<T>(descriptor)
     }
-    /**修复引用关系 */
+    /**
+     * 修复引用关系
+     * @param childs 子描述器数组
+     * @param map UUID映射表
+     */
     static fixReferences(childs: Descriptor[], map: Map<string, Descriptor>) {
         for (const child of childs) {
             for (const interaction of child.interactions) {
-                const keys = Object.keys(interaction.inputs)
+                const keys = Object.keys(interaction.nodes)
                 for (const key of keys) {
-                    const input = interaction.inputs[key]
-                    const attrs = Object.keys(input)
+                    const node = interaction.nodes[key]
+                    const attrs = Object.keys(node)
                     for (const attr of attrs) {
-                        const cur = input[attr]
+                        const cur = node[attr]
                         const clone = map.get(cur.value)
                         if (clone === undefined) continue
                         cur.value = clone.uuid
@@ -136,7 +112,11 @@ class Descriptor extends ObjectPool {
             }
         }
     }
-    /**创建镜像副本并修复引用关系 */
+    /**
+     * 创建镜像副本并修复引用关系
+     * @param descriptor 要克隆的描述器
+     * @returns 克隆后的描述器
+     */
     static cloneAndFixReferences(descriptor: Descriptor) {
         const map = new Map()
         const childs: Descriptor[] = []
@@ -146,48 +126,64 @@ class Descriptor extends ObjectPool {
         return clone
     }
 
-    static getPrefab(uuid: string) {
-        return privateState.instanceToPrefabCollection.get(uuid) ?? null
-    }
-    static getInstanceCollection(uuid: string) {
-        return privateState.prefabToInstanceCollection.get(uuid) ?? null
-    }
-
+    /**
+     * 类型标识
+     */
     readonly type: string
+    /**
+     * 子描述器数组
+     */
     readonly children: Descriptor[]
-    generatedBy = ''
+    /**
+     * 名称
+     */
     name: string
-    dataset: string
+    /**
+     * 数据容器
+     */
+    store: string
+    /**
+     * 变量配置
+     */
     variables: DescriptorVariables
-    interactions: InteractionPropertyCollection
+    /**
+     * 交互属性集合
+     */
+    interactions: InteractionPropertyArray
+    /**
+     * 是否可选择
+     */
     selectable: boolean
-    prefab: DescriptorPrefab | false
 
     constructor(descriptor: Partial<DeserializationObject<Descriptor>> = {}) {
         super(descriptor.uuid)
 
         this.type = (this.constructor as typeof Descriptor).type
         this.name = descriptor.name ?? ''
-        this.dataset = descriptor.dataset ?? ''
-        this.variables = descriptor.variables ? Descriptor.deepClone(descriptor.variables) : {}
-        this.interactions = descriptor.interactions ? Descriptor.deepClone(descriptor.interactions) : []
+        this.store = descriptor.store ?? ''
+        this.variables = DescriptorVariablesSchema.parse(descriptor.variables)
+        this.interactions = InteractionPropertyArraySchame.parse(descriptor.interactions)
         this.selectable = descriptor.selectable ?? true
-        this.prefab = descriptor.prefab ? Descriptor.deepClone(descriptor.prefab) : false
         //@ts-ignore
         this.children = []
 
-        privateState.setPrefabInstance(this)
-
         if (Array.isArray(descriptor.children) && descriptor.children.length > 0) {
             for (const subDescriptor of descriptor.children) this.add(Descriptor.create(subDescriptor))
         }
     }
 
+    /**
+     * 实例化时的回调
+     * @param instance 实例描述器
+     */
     protected beenInstantiated(instance: Descriptor): void {
         instance.clear()
     }
 
-    /**将`descriptor`添加到此节点中*/
+    /**
+     * 将`descriptor`添加到此节点中
+     * @param descriptor 要添加的描述器
+     */
     add(...descriptor: Descriptor[]) {
 
         for (const sub of descriptor) {
@@ -202,7 +198,10 @@ class Descriptor extends ObjectPool {
             observer.trigger('add', { self: sub.uuid, puid: this.uuid })
         }
     }
-    /**将`descriptor`从此节点中移除*/
+    /**
+     * 将`descriptor`从此节点中移除
+     * @param descriptor 要移除的描述器
+     */
     remove(...descriptor: Descriptor[]) {
         for (const sub of descriptor) {
             for (let i = 0; i < this.children.length; i++) {
@@ -219,6 +218,8 @@ class Descriptor extends ObjectPool {
     /**
      * 追踪描述器的祖先节点
      * @param all 追踪全部的祖先节点，默认为true
+     * @param depth 追踪深度，默认为Infinity
+     * @returns 祖先节点信息
      */
     traceAncestor<T extends Descriptor = Descriptor>(all = true, depth = Infinity) {
         let parent = privateState.getParent<T>(this.uuid)
@@ -242,7 +243,11 @@ class Descriptor extends ObjectPool {
         return ancestor
     }
 
-    /**将`uuid`节点插入到`target`节点中。*/
+    /**
+     * 将`uuid`节点插入到`target`节点中
+     * @param uuid 要插入的节点UUID
+     * @param target 目标节点UUID
+     */
     insert(uuid: string, target: string) {
         const insertNode = Descriptor.get<Descriptor>(uuid)
         if (insertNode === null) return console.warn(language.get('descriptor.insert.uuid.notFound', { uuid }))
@@ -255,7 +260,12 @@ class Descriptor extends ObjectPool {
         targetNode.add(insertNode)
     }
 
-    /**将`uuid`节点插入到`target`节点前。 */
+    /**
+     * 将`uuid`节点插入到`target`节点前
+     * @param uuid 要插入的节点UUID
+     * @param target 目标节点UUID
+     * @param offset 偏移量，默认为0
+     */
     insertBefore(uuid: string, target: string, offset = 0) {
         const insertNode = Descriptor.get<Descriptor>(uuid)
         if (insertNode === null) return console.warn(language.get('descriptor.insert.uuid.notFound', { uuid }))
@@ -284,12 +294,19 @@ class Descriptor extends ObjectPool {
             observer.trigger('add', { self: sub.uuid, puid: targetParent.uuid })
         }
     }
-    /**将`uuid`节点插入到`target`节点后。 */
+    /**
+     * 将`uuid`节点插入到`target`节点后
+     * @param uuid 要插入的节点UUID
+     * @param target 目标节点UUID
+     */
     insertAfter(uuid: string, target: string) {
         return this.insertBefore(uuid, target, 1)
     }
 
-    /**获取当前节点的邻接节点 */
+    /**
+     * 获取当前节点的邻接节点
+     * @returns 邻接节点信息
+     */
     getAdjacent() {
         const adjacent: DescriptorAdjacency = {
             parent: '',
@@ -312,6 +329,7 @@ class Descriptor extends ObjectPool {
      * 
      * 注意，该方法返回的描述器与原描述器uuid不相同
      * @param recursive 是否遍历克隆子节点，默认为true
+     * @returns 克隆后的描述器
      */
     clone<T extends Descriptor = Descriptor>(recursive = true) {
         const uuid = Generate.uuid()
@@ -320,16 +338,18 @@ class Descriptor extends ObjectPool {
         for (const sub of this.children) self.add(sub.clone(recursive))
         return self
     }
-    /**从同类型的对象上同步属性，不同步`uuid`、`children`和`type` */
+    /**
+     * 从同类型的对象上同步属性，不同步`uuid`、`children`和`type`
+     * @param descriptor 要同步的描述器
+     * @param ignore 要忽略的属性数组
+     */
     syncWith(descriptor: DeserializationObject<Descriptor>, ignore: string[] = []) {
-        if (this.type !== descriptor.type) return console.warn(language.get('descriptor.syncWith.fail'))
+        if (this.type !== descriptor.type) return console.warn(language.get('descriptor.syncWith.failed'))
 
-        const source = Descriptor.create({ ...descriptor, type: this.type, uuid: undefined, children: undefined }) as DeserializationObject
+        const source = Descriptor.create({ ...this,...descriptor, type: this.type, uuid: undefined, children: undefined }) as DeserializationObject
         delete source['uuid']
         delete source['type']
         delete source['children']
-        delete source['prefab']
-        delete source['generatedBy']
 
         for (const key of ignore) delete source[key]
 
@@ -339,6 +359,7 @@ class Descriptor extends ObjectPool {
      * 遍历所有节点
      * @param cb 遍历每个节点执行的回调
      * @param terminated 遍历是否可以被终止，默认false
+     * @param defaultParent 默认父节点
      */
     traverse<T extends Descriptor = Descriptor, D extends T | null = T | null>(cb: (sub: T, parent: D) => true | void, terminated = false, defaultParent: D = null as D) {
         if (terminated) {
@@ -347,20 +368,34 @@ class Descriptor extends ObjectPool {
             Traverser.pre(this as unknown as T, cb, defaultParent)
         }
     }
-    /**将子描述器全部移除 */
+    /**
+     * 将子描述器全部移除
+     */
     clear() {
         this.remove(...this.children)
     }
 
-    /**将对象序列化成json字符 */
+    /**
+     * 将对象序列化成json字符
+     * @returns 序列化后的json字符串
+     */
     serialization() {
         return Descriptor.serialization(this)
     }
 
+    /**
+     * 比较两个描述器是否相等
+     * @param descriptor 要比较的描述器
+     * @param ignore 要忽略的属性数组
+     * @returns 是否相等
+     */
     equals(descriptor: DeserializationObject<Descriptor>, ignore: string[] = ['children']) {
         return ObjectUtils.equals(this, descriptor, ignore)
     }
 
+    /**
+     * 设置需要更新
+     */
     setNeedsUpdate() {
         observer.trigger('update', { self: this.uuid })
     }
@@ -370,19 +405,4 @@ Descriptor.register(Descriptor)
 listenInstance('free', (uuid: string) => {
     observer.trigger('free', { self: uuid })
     privateState.refGraph.delete(uuid)
-    const prefab = privateState.instanceToPrefabCollection.get(uuid)
-    if (prefab === undefined) return
-    privateState.instanceToPrefabCollection.delete(uuid)
-    const instanceCollection = privateState.prefabToInstanceCollection.get(uuid)
-    if (instanceCollection === undefined) return
-    ArrayUtils.remove(instanceCollection, uuid)
-})
-
-export {
-    Descriptor,
-    DescriptorAdjacency,
-    DescriptorAncestor,
-    DescriptorPrefab,
-    VariabConfig,
-    DescriptorVariables,
-}
+})

package/src/descriptor/Div.ts

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