@vyr/three 0.0.33 → 0.0.36

package/src/descriptor/OrbitController.ts

@@ -0,0 +1,186 @@
+import { Controller, Descriptor, DeserializationObject, ScriptableArgs } from "@vyr/engine";
+
+/**
+ * OrbitController变更事件参数接口
+ * 定义了轨道控制器事件的参数结构
+ */
+export interface OrbitControllerChangeArgs extends ScriptableArgs {
+  /**事件信息 */
+  event: {
+    /**事件类型 */
+    type: string,
+    /**目标UUID */
+    target: string
+  }
+}
+
+/**
+ * OrbitController类
+ * 轨道控制器类，用于控制相机的轨道运动
+ * 
+ * 作用：提供相机的旋转、缩放、平移等交互控制功能
+ * 实现了Controller接口，可作为场景中的控制器使用
+ */
+export class OrbitController extends Descriptor implements Controller {
+  /**类类型标识 */
+  static type = 'OrbitController'
+
+  /**
+   * 控制器是否启用
+   * @default false
+   */
+  enabled: boolean
+  /**
+   * 最小距离
+   * 你能够将相机向内移动多少
+   * @default 0
+   */
+  minDistance: number
+  /**
+   * 最大距离
+   * 你能够将相机向外移动多少
+   * @default Infinity
+   */
+  maxDistance: number
+  /**
+   * 最小缩放
+   * 你能够将相机放大多少
+   * @default 0.01
+   */
+  minZoom: number
+  /**
+   * 最大缩放
+   * 你能够将相机缩小多少
+   * @default Infinity
+   */
+  maxZoom: number
+  /**
+   * 最小极角
+   * 你能够垂直旋转的角度的下限
+   * @default 0
+   */
+  minPolarAngle: number
+  /**
+   * 最大极角
+   * 你能够垂直旋转的角度的上限
+   * @default Math.PI * 2
+   */
+  maxPolarAngle: number
+  /**
+   * 最小方位角
+   * 你能够水平旋转的角度下限
+   * @default -Infinity
+   */
+  minAzimuthAngle: number
+  /**
+   * 最大方位角
+   * 你能够水平旋转的角度上限
+   * @default Infinity
+   */
+  maxAzimuthAngle: number
+  /**
+   * 边界摩擦系数
+   * @default 0
+   */
+  boundaryFriction: number
+  /**
+   * 边界是否包围相机
+   * 相机位置是否应包含在边界内
+   * @default false
+   */
+  boundaryEnclosesCamera: boolean
+  /**
+   * 平滑时间
+   * 到达目标的近似时间（秒），值越小到达目标越快
+   * @default 0.25
+   */
+  smoothTime: number
+  /**
+   * 拖动平滑时间
+   * 拖动时的平滑时间
+   * @default 0.125
+   */
+  draggingSmoothTime: number
+  /**
+   * 方位角旋转速度
+   * 水平旋转速度
+   * @default 1
+   */
+  azimuthRotateSpeed: number
+  /**
+   * 极角旋转速度
+   * 垂直旋转速度
+   * @default 1
+   */
+  polarRotateSpeed: number
+  /**
+   * 缩放速度
+   * 鼠标滚轮移动速度
+   * @default 1
+   */
+  dollySpeed: number
+  /**
+   * 平移速度
+   * 平移和升降的拖动速度
+   * @default 2
+   */
+  truckSpeed: number
+  /**
+   * 向光标缩放
+   * 是否启用向鼠标光标坐标移动
+   * @default false
+   */
+  dollyToCursor: boolean
+  /**
+   * 反转缩放方向
+   * 是否反转拖动时的移动或缩放方向
+   * @default false
+   */
+  dollyDragInverted: boolean
+  /**
+   * 无限缩放
+   * 是否启用滚轮和缩放的无限移动，与 minDistance 和 maxDistance 一起使用
+   * @default false
+   */
+  infinityDolly: boolean
+  /**
+   * 静止阈值
+   * 控制相机减速时 rest 事件触发的时机
+   * @default 0.0025
+   */
+  restThreshold: number
+  /**
+   * 事件脚本
+   * 控制器触发事件时执行的脚本依赖
+   * @default ""
+   */
+  event: string
+
+  constructor(descriptor: Partial<DeserializationObject<OrbitController>> = {}) {
+    super(descriptor)
+    this.enabled = descriptor.enabled ?? false
+    this.minDistance = descriptor.minDistance ?? 0
+    this.maxDistance = descriptor.maxDistance ?? Infinity
+    this.minPolarAngle = descriptor.minPolarAngle ?? 0
+    this.maxPolarAngle = descriptor.maxPolarAngle ?? Math.PI * 2
+    this.minAzimuthAngle = descriptor.minAzimuthAngle ?? -Infinity
+    this.maxAzimuthAngle = descriptor.maxAzimuthAngle ?? Infinity
+    this.minZoom = descriptor.minZoom ?? 0.01
+    this.maxZoom = descriptor.maxZoom ?? Infinity
+
+    this.boundaryFriction = descriptor.boundaryFriction ?? 0
+    this.boundaryEnclosesCamera = descriptor.boundaryEnclosesCamera ?? false
+    this.smoothTime = descriptor.smoothTime ?? 0.25
+    this.draggingSmoothTime = descriptor.draggingSmoothTime ?? 0.125
+    this.azimuthRotateSpeed = descriptor.azimuthRotateSpeed ?? 1
+    this.polarRotateSpeed = descriptor.polarRotateSpeed ?? 1
+    this.dollySpeed = descriptor.dollySpeed ?? 1
+    this.truckSpeed = descriptor.truckSpeed ?? 2
+    this.dollyToCursor = descriptor.dollyToCursor ?? false
+    this.dollyDragInverted = descriptor.dollyDragInverted ?? false
+    this.infinityDolly = descriptor.infinityDolly ?? false
+    this.restThreshold = descriptor.restThreshold ?? 0.0025
+    this.event = descriptor.event ?? ''
+  }
+}
+Descriptor.register(OrbitController)

package/src/descriptor/OrthographicCamera.ts

@@ -0,0 +1,19 @@
+import { Camera, DeserializationObject, Node } from "@vyr/engine"
+
+/**
+ * OrthographicCamera类
+ * 正交相机类，用于创建正交投影的相机
+ * 
+ * 作用：创建正交投影的相机，适用于2D场景或需要保持物体大小不变的3D场景
+ * 继承自Node类，拥有节点的所有空间变换属性
+ * 实现了Camera接口，可作为场景的相机使用
+ */
+export class OrthographicCamera extends Node implements Camera {
+    /**类类型标识 */
+    static type = 'OrthographicCamera'
+
+    constructor(descriptor: Partial<DeserializationObject<OrthographicCamera>> = {}) {
+        super(descriptor)
+    }
+}
+Node.register(OrthographicCamera)

package/src/descriptor/Particle.ts

@@ -0,0 +1,177 @@
+import { DeserializationObject, Euler, Node, Vector3 } from "@vyr/engine"
+import { MaterialDepthFunc, MaterialDlending, MaterialSide } from "./material/Material"
+
+/**
+ * Particle类
+ * 粒子类，用于创建和控制粒子系统
+ * 
+ * 作用：通过配置参数创建各种粒子效果，如烟雾、火焰、雨滴等
+ * 继承自Node类，拥有节点的所有空间变换属性
+ */
+export class Particle extends Node {
+    /**类类型标识 */
+    static type = 'Particle'
+
+    /**
+     * 粒子数量
+     * @default 0
+     */
+    count: number
+    /**
+     * 轨迹数据引用，使用`Store`的URL作为有效值
+     * @default ""
+     */
+    track: string
+    /**
+     * 粒子运行时间
+     * @default 0
+     */
+    duration: number
+    /**
+     * 最小粒子尺寸
+     * @default 1
+     */
+    minSize: number
+    /**
+     * 最大粒子尺寸
+     * @default 1
+     */
+    maxSize: number
+    /**
+     * 最小轨迹偏移
+     * @default {x:0,y:0,z:0}
+     */
+    minTrackOffset: Vector3
+    /**
+     * 最大轨迹偏移
+     * @default {x:0,y:0,z:0}
+     */
+    maxTrackOffset: Vector3
+    /**
+     * 最小轨迹缩放
+     * @default {x:1,y:1,z:1}
+     */
+    minTrackScale: Vector3
+    /**
+     * 最大轨迹缩放
+     * @default {x:1,y:1,z:1}
+     */
+    maxTrackScale: Vector3
+    /**
+     * 最小轨迹旋转
+     * @default {x:0,y:0,z:0,order:'XYZ'}
+     */
+    minTrackRotation: Euler
+    /**
+     * 最大轨迹旋转
+     * @default {x:0,y:0,z:0,order:'XYZ'}
+     */
+    maxTrackRotation: Euler
+    /**
+     * 透明度测试
+     * @default 0
+     */
+    alphaTest: number
+    /**
+     * 材质是否透明
+     * @default false
+     */
+    transparent: boolean
+    /**
+     * 材质类型
+     * @default MaterialSide.FrontSide
+     */
+    side: number
+    /**
+     * 是否渲染材质的颜色
+     * @default true
+     */
+    colorWrite: boolean
+    /**
+     * 是否启用深度测试
+     * @default true
+     */
+    depthTest: boolean
+    /**
+     * 是否写入深度
+     * @default true
+     */
+    depthWrite: boolean
+    /**
+     * 深度函数
+     * @default MaterialDepthFunc.LessEqualDepth
+     */
+    depthFunc: number
+    /**
+     * 混合函数
+     * 混合效果见 https://threejs.org/examples/#webgl_materials_blending
+     * @default MaterialDlending.NormalBlending
+     */
+    blending: number
+    /**
+     * 是否使用顶点着色
+     * @default false
+     */
+    vertexColors: boolean
+    /**
+     * 漫反射颜色
+     * @default '#ffffff'
+     */
+    color: string
+    /**
+     * 透明度
+     * @default 1
+     */
+    opacity: number
+    /**
+     * 漫反射贴图
+     * @default ""
+     */
+    map: string
+    /**
+     * 透明度贴图
+     * @default ""
+     */
+    alphaMap: string
+    /**
+     * 点的大小是否会被相机深度衰减
+     * @default true
+     */
+    sizeAttenuation: boolean
+    /**
+     * 材质是否受雾影响
+     * @default true
+     */
+    fog: boolean
+
+    constructor(descriptor: Partial<DeserializationObject<Particle>> = {}) {
+        super(descriptor)
+        this.count = descriptor.count ?? 0
+        this.track = descriptor.track ?? ''
+        this.duration = descriptor.duration ?? 0
+        this.minSize = descriptor.minSize ?? 1
+        this.maxSize = descriptor.maxSize ?? 1
+        this.minTrackOffset = Vector3.create(descriptor.minTrackOffset)
+        this.maxTrackOffset = Vector3.create(descriptor.maxTrackOffset)
+        this.minTrackScale = descriptor.minTrackScale ? Vector3.create(descriptor.minTrackScale) : new Vector3(1, 1, 1)
+        this.maxTrackScale = descriptor.maxTrackScale ? Vector3.create(descriptor.maxTrackScale) : new Vector3(1, 1, 1)
+        this.minTrackRotation = Euler.create(descriptor.minTrackRotation)
+        this.maxTrackRotation = Euler.create(descriptor.maxTrackRotation)
+        this.alphaTest = descriptor.alphaTest ?? 0
+        this.transparent = descriptor.transparent ?? false
+        this.side = descriptor.side ?? MaterialSide.FrontSide
+        this.colorWrite = descriptor.colorWrite ?? true
+        this.depthTest = descriptor.depthTest ?? true
+        this.depthWrite = descriptor.depthWrite ?? true
+        this.depthFunc = descriptor.depthFunc ?? MaterialDepthFunc.LessEqualDepth
+        this.blending = descriptor.blending ?? MaterialDlending.NormalBlending
+        this.vertexColors = descriptor.vertexColors ?? false
+        this.color = descriptor.color ? descriptor.color : '#ffffff'
+        this.opacity = descriptor.opacity ?? 1
+        this.map = descriptor.map ?? ''
+        this.alphaMap = descriptor.alphaMap ?? ''
+        this.sizeAttenuation = descriptor.sizeAttenuation ?? true
+        this.fog = descriptor.fog ?? true
+    }
+}
+Node.register(Particle)

package/src/descriptor/Pass.ts

@@ -0,0 +1,54 @@
+import { Descriptor, DeserializationObject } from "@vyr/engine";
+
+/**
+ * 效果通道接口
+ * 定义了渲染通道中的效果
+ */
+export interface EffectPass {
+
+}
+
+/**
+ * Pass类
+ * 渲染通道类，用于后期处理效果
+ * 
+ * 作用：作为后期处理的基本单元，包含各种渲染效果
+ * 继承自Descriptor类，拥有描述器的所有属性和方法
+ * 
+ * TODO 继续实现渲染通道
+ */
+export class Pass extends Descriptor {
+    /**类类型标识 */
+    static type = 'Pass'
+
+    /**
+     * 是否启用通道
+     * @default true
+     */
+    enabled: boolean
+    /**
+     * 是否需要交换缓冲
+     * @default false
+     */
+    needsSwap: boolean
+    /**
+     * 是否需要为此材质准备深度纹理
+     * @default false
+     */
+    needsDepthTexture: boolean
+    /**
+     * 该通道的效果
+     * @default []
+     */
+    effects: EffectPass[]
+
+    constructor(descriptor: Partial<DeserializationObject<Pass>> = {}) {
+        super(descriptor)
+        this.enabled = descriptor.enabled ?? true
+        this.needsSwap = descriptor.needsSwap ?? false
+        this.needsDepthTexture = descriptor.needsDepthTexture ?? false
+        this.effects = descriptor.effects ? Descriptor.deepClone(descriptor.effects) : []
+    }
+}
+
+Descriptor.register(Pass)

package/src/descriptor/PerspectiveCamera.ts

@@ -0,0 +1,27 @@
+import { Camera, DeserializationObject, Node } from "@vyr/engine"
+
+/**
+ * PerspectiveCamera类
+ * 透视相机类，用于创建透视投影的相机
+ * 
+ * 作用：创建具有透视效果的相机，适用于大多数3D场景
+ * 继承自Node类，拥有节点的所有空间变换属性
+ * 实现了Camera接口，可作为场景的相机使用
+ */
+export class PerspectiveCamera extends Node implements Camera {
+    /**类类型标识 */
+    static type = 'PerspectiveCamera'
+
+    /**
+     * 视场角
+     * 相机的垂直视场角，以度为单位
+     * @default 45
+     */
+    fov: number
+
+    constructor(descriptor: Partial<DeserializationObject<PerspectiveCamera>> = {}) {
+        super(descriptor)
+        this.fov = descriptor.fov ?? 45
+    }
+}
+Node.register(PerspectiveCamera)

package/src/descriptor/Points.ts

@@ -0,0 +1,32 @@
+import { DeserializationObject, Node } from "@vyr/engine"
+
+/**
+ * Points类
+ * 点云类，用于创建和显示点云对象
+ * 
+ * 作用：通过几何体和材质创建点云效果，可用于表示粒子系统、点数据集等
+ * 继承自Node类，拥有节点的所有空间变换属性
+ */
+export class Points extends Node {
+    /**类类型标识 */
+    static type = 'Points'
+    /**
+     * 材质
+     * 点云的材质，使用`Material`资源的URL作为有效值
+     * @default ""
+     */
+    material: string
+    /**
+     * 几何体
+     * 点云的几何体，使用`Geometry`资源的URL作为有效值
+     * @default ""
+     */
+    geometry: string
+
+    constructor(descriptor: Partial<DeserializationObject<Points>> = {}) {
+        super(descriptor)
+        this.material = descriptor.material ?? ''
+        this.geometry = descriptor.geometry ?? ''
+    }
+}
+Node.register(Points)

package/src/descriptor/Scene3DService.ts

@@ -0,0 +1,80 @@
+import { Descriptor, DeserializationObject, HtmlAttributes, HtmlAttributesSchema, registerService, Service } from "@vyr/engine"
+
+/**
+ * 场景阴影类型枚举
+ * 定义了不同质量的阴影贴图类型
+ */
+export enum SceneShadow {
+    /**基础阴影贴图，性能最佳但质量较低 */
+    BasicShadowMap = 0,
+    /**PCF阴影贴图，平衡性能与质量 */
+    PCFShadowMap = 1,
+    /**PCF软阴影贴图，质量较高但性能消耗较大 */
+    PCFSoftShadowMap = 2,
+    /**VSM阴影贴图，支持透明物体阴影 */
+    VSMShadowMap = 3,
+}
+
+/**
+ * SceneService类
+ * 三维场景渲染服务
+ * 
+ * 作用：负责管理三维节点（如Node、Mesh、Model等）的渲染。必须作为Scene的直接子节点挂载，
+ * 否则所有三维节点将无法正常渲染。
+ * 
+ * 使用要求：
+ * 1. 必须添加为Scene的子节点
+ * 2. 在场景中仅需一个实例
+ * 3. 应在其他三维节点之前初始化
+ * 
+ * @example
+ * // 场景结构示例
+ * Scene
+ * └── Scene3DService  // 必须在此位置
+ *     └── Mesh          // 依赖此服务才能渲染
+ */
+export class Scene3DService extends Descriptor implements Service {
+    /**类类型标识 */
+    static type = 'Scene3DService'
+
+    readonly isHTML = true
+
+    visible: boolean
+
+    htmlAttributes: HtmlAttributes
+
+    /**
+     * 是否开启阴影贴图
+     * @default true
+     */
+    shadowMap: boolean
+    /**
+     * 阴影贴图类型
+     * @default SceneShadow.BasicShadowMap
+     */
+    shadowMapType: SceneShadow
+    /**
+     * 是否自动更新阴影贴图
+     * @default false
+     */
+    autoUpdateShadowMap: boolean
+    /**
+     * 背景贴图
+     * 使用`Texture`资源的URL作为有效值
+     * @default ""
+     */
+    backgroundMap: string
+
+    constructor(descriptor: Partial<DeserializationObject<Scene3DService>> = {}) {
+        super(descriptor)
+        this.visible = descriptor.visible ?? true
+        this.htmlAttributes = HtmlAttributesSchema.parse(descriptor.htmlAttributes)
+        this.shadowMap = descriptor.shadowMap ?? true
+        this.shadowMapType = descriptor.shadowMapType ?? SceneShadow.BasicShadowMap
+        this.autoUpdateShadowMap = descriptor.autoUpdateShadowMap ?? false
+        this.backgroundMap = descriptor.backgroundMap ?? ''
+    }
+}
+
+Descriptor.register(Scene3DService)
+registerService(Scene3DService.type)

package/src/descriptor/Sprite.ts

@@ -0,0 +1,27 @@
+import { DeserializationObject, Node, Vector2 } from "@vyr/engine"
+
+/**
+ * Sprite类
+ * 精灵对象，用于2D图像渲染
+ * 
+ * 作用：创建和管理精灵实例，支持设置材质和中心点
+ */
+export class Sprite extends Node {
+    /**类类型标识 */
+    static type = 'Sprite'
+    /**精灵的材质，使用`Material`资源的URL作为有效值
+     *  @default ""
+     */
+    material: string
+    /**精灵中心点坐标，范围0-1
+     *  @default {x:0.5, y:0.5}
+     */
+    center: Vector2
+
+    constructor(descriptor: Partial<DeserializationObject<Sprite>> = {}) {
+        super(descriptor)
+        this.material = descriptor.material ?? ''
+        this.center = descriptor.center ? Vector2.create(descriptor.center) : Vector2.create(0.5, 0.5)
+    }
+}
+Node.register(Sprite)

package/src/descriptor/Text3D.ts

@@ -0,0 +1,51 @@
+import { DeserializationObject, Node } from '@vyr/engine'
+
+/**
+ * Text类
+ * 文本节点，用于渲染3D文本
+ * 
+ * 作用：创建和管理3D文本实例，支持设置字体、大小、行高等属性
+ */
+export class Text3D extends Node {
+    /**类类型标识 */
+    static type = 'Text3D'
+
+    /**字体资源，指向字体文件的URL @default "" */
+    font: string
+    /**文本大小 @default 1 */
+    size: number
+    /**文本最大宽度，超过会自动换行 @default Infinity */
+    maxWidth: number
+    /**行高倍数 @default 1.5 */
+    lineHeight: number
+    /**字符间距 @default 0 */
+    letterSpacing: number
+    /**文本内容 @default "" */
+    text: string
+    /**是否将UV展平到平面 @default false */
+    flattenUVsToPlane: boolean
+    /**曲线分段数，影响文本平滑度 @default 12 */
+    curveSegments: number
+    /**文本厚度方向的步数 @default 1 */
+    steps: number
+    /**文本厚度 @default 1 */
+    depth: number
+    /**材质引用，指向材质资源的唯一标识 @default "" */
+    material: string
+
+    constructor(descriptor: Partial<DeserializationObject<Text3D>> = {}) {
+        super(descriptor)
+        this.font = descriptor.font ?? ''
+        this.size = descriptor.size ?? 1
+        this.maxWidth = descriptor.maxWidth ?? Infinity
+        this.lineHeight = descriptor.lineHeight ?? 1.5
+        this.letterSpacing = descriptor.letterSpacing ?? 0
+        this.text = descriptor.text ?? ''
+        this.flattenUVsToPlane = descriptor.flattenUVsToPlane ?? false
+        this.curveSegments = descriptor.curveSegments ?? 12
+        this.steps = descriptor.steps ?? 1
+        this.depth = descriptor.depth ?? 1
+        this.material = descriptor.material ?? ''
+    }
+}
+Node.register(Text3D)

package/src/descriptor/TransformController.ts

@@ -0,0 +1,33 @@
+import { Controller, Descriptor, DeserializationObject } from "@vyr/engine";
+
+/**
+ * TransformController类
+ * 变换控制器，用于控制3D对象的变换操作
+ * 
+ * 作用：提供对3D对象的平移、旋转、缩放等变换操作的控制
+ */
+export class TransformController extends Descriptor implements Controller {
+  /**类类型标识 */
+  static type = 'TransformController'
+
+  /**是否启用控制器 @default false */
+  enabled: boolean
+  /**控制器使用的摄像机引用 @default "" */
+  camera: string
+  /**控制器的模式（如translate、rotate、scale） @default "" */
+  mode: string
+  /**控制器的目标对象引用 @default "" */
+  target: string
+  /**控制器触发事件时执行的脚本依赖 @default "" */
+  event: string
+
+  constructor(descriptor: Partial<DeserializationObject<TransformController>> = {}) {
+    super(descriptor)
+    this.enabled = descriptor.enabled ?? false
+    this.camera = descriptor.camera ?? ''
+    this.mode = descriptor.mode ?? ''
+    this.target = descriptor.target ?? ''
+    this.event = descriptor.event ?? ''
+  }
+}
+Descriptor.register(TransformController)