@vvfx/sdk 0.1.19-alpha.9 → 0.2.0

package/dist/src/math/line2.d.ts

@@ -0,0 +1,93 @@
+import { Vector2 } from './vector2';
+/**
+ * @class 二维线段
+ */
+export declare class Line2 {
+    start: Vector2;
+    end: Vector2;
+    constructor(start?: Vector2, end?: Vector2);
+    /**
+     * 设置二维线段
+     * @param {Vector2} start 线段起点
+     * @param {Vector2} end 线段终点
+     * @returns {Line2} 二维线段
+     */
+    set(start: Vector2, end: Vector2): this;
+    /**
+     * 复制二维线段
+     * @param {Line2} line 复制对象
+     * @returns {Line2} 复制结果
+     */
+    copyFrom(line: Line2): this;
+    /**
+     * 二维线段求方向
+     * @returns {Vector2} 二维线段方向
+     */
+    direction(): Vector2;
+    /**
+     * 二维线段求中点
+     * @param {Vector2} [target=new Vector2()] 目标保存对象
+     * @returns {Vector2} 二维线段中点
+     */
+    getCenter(target?: Vector2): Vector2;
+    /**
+     * 二维线段向量值
+     * @param {Vector2} [target=new Vector2()] 目标保存对象
+     * @returns {Vector2} 二维线段向量值
+     */
+    delta(target?: Vector2): Vector2;
+    /**
+     * 二维线段欧式距离平方(应用于计算)
+     * @returns {number} 计算结果
+     */
+    distanceSq(): number;
+    /**
+     * 二维线段欧式距离
+     * @returns {number} 计算结果
+     */
+    distance(): number;
+    /**
+     * 求二维线段比例点
+     * @param {number} t 比例值
+     * @param {Vector2} target 目标保存对象
+     * @returns {Vector2} 比例点结果
+     */
+    at(t: number, target?: Vector2): Vector2;
+    /**
+     * 求点与线段的最短距离
+     * @param {Vector2} point 二维空间点
+     * @param {boolean} clampToLine 是否限制于线段内
+     * @returns {number} 距离结果
+     */
+    closestPointToPointParameter(point: Vector2, clampToLine: boolean): number;
+    /**
+     * 求点与线段的最近交点
+     * @param {Vector2} point 二维空间点
+     * @param {boolean} clampToLine 是否限制于线段内
+     * @param {Vector2} target 目标保存对象
+     * @returns {Vector2} 最近交点
+     */
+    closestPointToPoint(point: Vector2, clampToLine: boolean, target?: Vector2): Vector2;
+    /**
+     * 二维线段判等
+     * @param {Line2} line 二维线段
+     * @returns {boolean} 判等结果
+     */
+    equals(line: Line2): boolean;
+    /**
+     * 克隆二维线段
+     * @returns {Line2} 克隆结果
+     */
+    clone(): Line2;
+    /**
+     * 二维线段求长度
+     * @returns {number} 长度
+     */
+    length(): number;
+    /**
+     * 二维线段判断相交
+     * @param {Line2} other 二维线段
+     * @returns {boolean} 相交判断结果
+     */
+    crossWithLine(other: Line2): boolean;
+}

package/dist/src/math/line3.d.ts

@@ -0,0 +1,17 @@
+import { Vector3 } from './vector3';
+/**
+ * @class 三维线段
+ */
+export declare class Line3 {
+    start: Vector3;
+    end: Vector3;
+    /**
+     * 构造函数
+     * @param {Vector3} [start=new Vector3()] 线段起点，默认值为(0, 0, 0)
+     * @param {Vector3} [end=new Vector3()] 线段终点，默认值为(0, 0, 0)
+     */
+    constructor(start?: Vector3, end?: Vector3);
+    closestPointToPointParameter(point: Vector3, clampToLine?: boolean): number;
+    closestPointToPoint(point: Vector3, clampToLine?: boolean): Vector3;
+    delta(): Vector3;
+}

package/dist/src/math/matrix4.d.ts

@@ -0,0 +1,28 @@
+import { math } from '../shared';
+import type { Euler } from './euler';
+import type { Quaternion } from './quaternion';
+import { Vector3 } from './vector3';
+export declare class Matrix4 extends math.Matrix4 {
+    /**
+     * 通过数组创建矩阵
+     * @param array - 数组
+     * @param [offset=0] - 起始偏移值
+     * @returns 矩阵
+     */
+    static fromArray(array: math.Matrix4DataType, offset?: number): Matrix4;
+    clone(): Matrix4;
+    compose(translation: Vector3, rotation: Quaternion, scale: Vector3, anchor?: math.Vector3): this;
+    /**
+     * 导出四维矩阵[三维空间变换矩阵]旋转部分
+     * @param {Matrix4} m 四维矩阵
+     * @returns {Matrix4} 导出结果
+     */
+    extractRotation(m: Matrix4): this;
+    /**
+     * 由欧拉角设置四维矩阵
+     * @param {Euler} euler 欧拉角
+     * @returns {Matrix4} 四维矩阵
+     */
+    makeRotationFromEuler(euler: Euler): this;
+    setPosition(position: Vector3): this;
+}

package/dist/src/math/plane.d.ts

@@ -0,0 +1,14 @@
+import { Vector3 } from './vector3';
+export declare class Plane {
+    distance: number;
+    normal: Vector3;
+    constructor(distance?: number, normal?: Vector3);
+    static set(distance: number, normal: Vector3): Plane;
+    set(distance: number, normal: Vector3): this;
+    static copy(target: Plane): Plane;
+    copy(target: Plane): this;
+    static setFromNormalAndCoplanarPoint(point: Vector3, normal: Vector3): Plane;
+    setFromNormalAndCoplanarPoint(point: Vector3, normal: Vector3): this;
+    clone(): Plane;
+    distanceToPoint(point: Vector3): number;
+}

package/dist/src/math/quaternion.d.ts

@@ -0,0 +1,3 @@
+import { math } from '../shared';
+export declare class Quaternion extends math.Quaternion {
+}

package/dist/src/math/ray-caster.d.ts

@@ -0,0 +1,10 @@
+import type { Plane } from './plane';
+import { Ray } from './ray';
+import type { RayCasterCamera, RayCastResult } from './type';
+import type { Vector2 } from './vector2';
+export declare class RayCaster {
+    ray: Ray;
+    constructor(ray?: Ray);
+    setFromCamera(coords: Vector2, camera: RayCasterCamera): this;
+    rayCastPlane(plane: Plane): RayCastResult | undefined;
+}

package/dist/src/math/ray.d.ts

@@ -0,0 +1,18 @@
+import { math } from '../shared';
+import type { Plane } from './plane';
+import { Vector3 } from './vector3';
+export declare class Ray extends math.Ray {
+    origin: Vector3;
+    direction: Vector3;
+    constructor(origin?: Vector3, direction?: Vector3);
+    clone(): Ray;
+    rayCastPlane(plane: Plane, _target: Vector3): number;
+    at(t: number): Vector3;
+    /**
+     * 射线到平面的距离
+     * 当两个向量都是单位向量的时候，从a投影到b的距离等于从b投影到a的距离
+     * @param plane 平面
+     * @returns 射线到平面的距离
+     */
+    distanceToPlane(plane: Plane): number;
+}

package/dist/src/math/type.d.ts

@@ -0,0 +1,32 @@
+import type { Matrix4 } from './matrix4';
+import type { Vector3 } from './vector3';
+/**
+ * 射线碰撞相机参数
+ */
+export type RayCasterCamera = {
+    /**
+     * 位置
+     */
+    position: Vector3;
+    /**
+     * 视图投影逆矩阵
+     */
+    inverseViewProjectMatrix: Matrix4;
+};
+/**
+ * 射线碰撞结果
+ */
+export type RayCastResult = {
+    /**
+     * 相交点
+     */
+    point: Vector3;
+    /**
+     * 相交距离
+     */
+    distance: number;
+    /**
+     * 相交构件ID
+     */
+    id?: string;
+};

package/dist/src/math/utils.d.ts

@@ -0,0 +1,19 @@
+import { Box2 } from './box2';
+import { Vector2 } from './vector2';
+export declare function clamp(value: number, min: number, max: number): number;
+/**
+ * @description 角度转弧度系数
+ */
+export declare const DEG2RAD: number;
+/**
+ * @description 弧度转角度系数
+ */
+export declare const RAD2DEG: number;
+export declare function getVector2Angle(vector: Vector2): number;
+export declare function getAngleByVectors(vector1: Vector2, vector2: Vector2): number;
+export declare function roundNumber(number: number, precision: number, method?: (x: number) => number): number;
+export declare function getAbsMaxIndex(numbers: number[]): number;
+export declare function isEqual(a: number, b: number): boolean;
+export declare function isZero(v: number): boolean;
+export declare function getBoxByNormalizeBox(origin: Box2, normalize: Box2): Box2;
+export declare function getNormalizeBoxByBoxes(origin: Box2, current: Box2): Box2;

package/dist/src/math/vector2.d.ts

@@ -0,0 +1,30 @@
+import { math } from '../shared';
+import { Line2 } from './line2';
+export declare class Vector2 extends math.Vector2 {
+    subtract(other: Vector2): this;
+    toViewCoordinate(width: number, height: number): this;
+    clone(): Vector2;
+    distanceTo(other: Vector2): number;
+    scaleByCenter(scalar: Vector2, anchor?: Vector2): this;
+    round(precision?: number): this;
+    /**
+     * 点到直线的最短距离
+     * @returns {{d: number, t: number}} d表示距离，t表示最近点在直线的比例
+     */
+    distanceToLine(line: Line2): {
+        d: number;
+        t: number;
+    };
+    /**
+     * 二维向量与x轴夹角
+     * @returns {number} 弧度值
+     */
+    angle(): number;
+    /**
+     * 二维点绕点旋转
+     * @param {Vec2} center 旋转中心
+     * @param {number} angle 旋转角度
+     * @returns {Vec2} 旋转结果
+     */
+    rotateAround(center: Vector2, angle: number): this;
+}

package/dist/src/math/vector3.d.ts

@@ -0,0 +1,29 @@
+import { math } from '../shared';
+import type { Euler } from './euler';
+import type { Matrix4 } from './matrix4';
+import { Quaternion } from './quaternion';
+export declare class Vector3 extends math.Vector3 {
+    clone(): Vector3;
+    /**
+     * 由空间变换矩阵保存三维分量
+     * @param {Matrix4} m 四维矩阵
+     * @param {number} index 下标
+     * @returns {Vec3} 指定三维分量
+     */
+    setFromMatrixColumn(m: Matrix4, index: number): this;
+    applyEuler(euler: Euler, _out?: Vector3): this;
+    /**
+     * 三维点根据四元数绕点的旋转
+     * @param {Quaternion} q 四元数
+     * @param {Vec3} [center=new Vec3()] 旋转中心
+     * @returns {Vec3} 旋转结果
+     */
+    applyQuaternion(q: Quaternion, center?: Vector3): this;
+    /**
+     * 由空间变换矩阵保存三维偏移值
+     * @param {Matrix4} m 四维矩阵
+     * @returns {Vec3} 偏移值
+     */
+    setFromMatrixPosition(m: Matrix4): this;
+    applyMatrix(matrix: Matrix4, center?: Vector3): this;
+}

package/dist/src/screen-shot/index.d.ts

@@ -0,0 +1 @@
+export * from './screen-shot';

package/dist/src/screen-shot/screen-shot.d.ts

@@ -0,0 +1,35 @@
+import { spec } from '../shared';
+/**
+ * @description 截图工具
+ */
+export declare class ScreenShot {
+    /**
+     * @description 功能开关
+     */
+    enabled: boolean;
+    /**
+     * @description 截图播放器
+     */
+    private _player;
+    /**
+     * @description 截图播放器容器
+     */
+    private _container;
+    constructor();
+    /**
+     * @description 生成截图
+     * @param scene 场景数据
+     * @param resultSize 截图大小
+     * @param tick 截图时刻
+     * @param screenArea 截图范围【可选】 - [左上角x坐标， 左上角y坐标， 截图宽度， 截图高度]
+     * @returns 截图base64数据
+     */
+    generate(scene: spec.JSONScene | string, containerSize: spec.vec2, resultSize: spec.vec2, tick: number, background?: spec.vec4): Promise<string | undefined>;
+    dispose(): void;
+    drawImageCover(ctx: CanvasRenderingContext2D, img: HTMLImageElement | HTMLCanvasElement | HTMLVideoElement, x: number, y: number, w: number, h: number, offsetX?: number, offsetY?: number, sourceRect?: {
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+    }): void;
+}

package/dist/src/sdk-item/base-item.d.ts

@@ -0,0 +1,126 @@
+import type { BaseItemProperty, ItemCreateInfo } from '../types';
+import { spec } from '../shared';
+import type { SDKItemOptions, SDKItemType } from './types';
+/**
+ * @description SDKItem 抽象基类
+ * @description 支持属性扩展，允许添加任意自定义属性
+ */
+export declare abstract class BaseItem {
+    /**
+     * @description 元素ID
+     */
+    id: string;
+    /**
+     * @description 元素名称
+     */
+    name: string;
+    /**
+     * @description 父节点ID
+     */
+    parentId?: string;
+    /**
+     * @description 元素生命周期
+     */
+    duration: number;
+    /**
+     * @description 元素生命周期延时
+     */
+    delay: number;
+    /**
+     * @description 元素结束行为
+     */
+    endBehavior: spec.EndBehavior;
+    /**
+     * @description 是否可见
+     */
+    visible: boolean;
+    /**
+     * @description 是否处于锁定状态
+     */
+    isLocked: boolean;
+    /**
+     * @description 核心数据是否支持编辑
+     */
+    isCoreEditable: boolean;
+    /**
+     * @description 扩展属性存储（与 property 同级）
+     */
+    extension: Map<string, any>;
+    /**
+     * @description 元素类型（由子类实现）
+     * @description 支持 spec.ItemType 或扩展的 SDKItemType
+     */
+    abstract readonly type: SDKItemType;
+    /**
+     * @description 元素属性（由子类实现）
+     */
+    abstract readonly property: BaseItemProperty;
+    constructor(options: SDKItemOptions);
+    get pixelWidth(): number;
+    get pixelHeight(): number;
+    /**
+     * @description 设置扩展属性
+     * @param key 属性名
+     * @param value 属性值
+     */
+    setExtension(key: string, value: any): void;
+    /**
+     * @description 获取扩展属性
+     * @param key 属性名
+     * @returns 属性值
+     */
+    getExtension(key: string): any;
+    /**
+     * @description 检查是否存在指定扩展属性
+     * @param key 属性名
+     * @returns 是否存在
+     */
+    hasExtension(key: string): boolean;
+    /**
+     * @description 删除扩展属性
+     * @param key 属性名
+     * @returns 是否删除成功
+     */
+    deleteExtension(key: string): boolean;
+    /**
+     * @description 获取所有扩展属性的键名列表
+     * @returns 键名数组
+     */
+    getExtensionKeys(): string[];
+    /**
+     * @description 获取所有扩展属性
+     * @returns 扩展属性对象
+     */
+    getAllExtension(): Record<string, any>;
+    /**
+     * @description 批量设置扩展属性
+     * @param extensions 扩展属性对象
+     */
+    setExtensions(extensions: Record<string, any>): void;
+    /**
+     * @description 清空所有扩展属性
+     */
+    clearExtension(): void;
+    /**
+     * @description 转换为 CreateInfo（用于元素复制/导出）
+     * @param withParent 是否包含父节点ID
+     * @returns CreateInfo 对象
+     */
+    abstract toCreateInfo(withParent?: boolean): ItemCreateInfo;
+    /**
+     * @description 克隆 SDKItem
+     * @returns 新的 SDKItem 实例
+     */
+    abstract clone(): BaseItem;
+    /**
+     * @description 获取基础属性的 JSON 对象,转换为普通对象（用于序列化）
+     * @returns 普通对象
+     */
+    toJSON(): Record<string, any>;
+}
+/**
+ * @description 类型守卫函数：检查对象是否是 BaseItem
+ * @param obj 要检查的对象
+ * @returns 是否是 BaseItem 实例
+ */
+export declare function isBaseItem(obj: any): obj is BaseItem;

package/dist/src/sdk-item/card-item.d.ts

@@ -0,0 +1,67 @@
+import type { CardItemProperty, CardCreateInfo, CardHTML } from '../types';
+import { SDKItemType, type CardItemOptions } from './types';
+import { BaseItem } from './base-item';
+/**
+ * @description 卡片元素 SDKItem 类
+ * @description 在 Player 中以 SpriteItem 形式渲染（透明占位，无图）
+ * @description 支持设置卡片类型（cardType）
+ */
+export declare class CardItem extends BaseItem {
+    /**
+     * @description 元素类型
+     */
+    readonly type = SDKItemType.CARD;
+    /**
+     * @description 元素属性（包含 cardType）
+     */
+    property: CardItemProperty;
+    constructor(options: CardItemOptions);
+    /**
+     * @description 卡片类型
+     */
+    get cardType(): string;
+    set cardType(value: string);
+    /**
+     * @description HTML 覆盖层配置
+     */
+    get html(): CardHTML | undefined;
+    set html(value: CardHTML | undefined);
+    /**
+     * @description 位置
+     */
+    get position(): [number, number];
+    set position(value: [number, number]);
+    /**
+     * @description 宽度
+     */
+    get width(): number;
+    set width(value: number);
+    /**
+     * @description 高度
+     */
+    get height(): number;
+    set height(value: number);
+    /**
+     * @description 旋转（二维旋转角度）
+     */
+    get rotation(): number;
+    set rotation(value: number);
+    /**
+     * @description 完整旋转（包含 x, y, z）
+     */
+    get fullRotation(): [number, number, number];
+    set fullRotation(value: [number, number, number]);
+    /**
+     * @description 转换为 CardCreateInfo
+     * @param withParent 是否包含父节点ID
+     */
+    toCreateInfo(withParent?: boolean): CardCreateInfo;
+    /**
+     * @description 克隆 SDKItem
+     */
+    clone(): CardItem;
+}
+/**
+ * @description 类型守卫：检查是否是 CardItem
+ */
+export declare function isCardItem(obj: any): obj is CardItem;

package/dist/src/sdk-item/effects-item.d.ts

@@ -0,0 +1,70 @@
+import type { EffectsCreateInfo, EffectsItemProperty } from '../types';
+import { SDKItemType, EffectsItemOptions } from './types';
+import { BaseItem } from './base-item';
+/**
+ * @description 特效产物 元素 SDKItem 类
+ */
+export declare class EffectsItem extends BaseItem {
+    /**
+     * @description 元素类型（独立类型，不属于 spec.ItemType）
+     */
+    readonly type = SDKItemType.EFFECTS;
+    /**
+     * @description 预合成元素ID
+     */
+    subCompositionItemId: string;
+    /**
+     * @description 元素属性
+     */
+    property: EffectsItemProperty;
+    constructor(options: EffectsItemOptions);
+    /**
+     * @description 特效资源地址
+     */
+    get effects(): string;
+    set effects(value: string);
+    /**
+     * @description 位置
+     */
+    get position(): [number, number];
+    set position(value: [number, number]);
+    /**
+     * @description 宽度
+     */
+    get width(): number;
+    set width(value: number);
+    /**
+     * @description 高度
+     */
+    get height(): number;
+    set height(value: number);
+    /**
+     * @description 旋转（二维旋转角度）
+     */
+    get rotation(): number;
+    set rotation(value: number);
+    /**
+     * @description 完整旋转（包含 x, y, z）
+     */
+    get fullRotation(): [number, number, number];
+    set fullRotation(value: [number, number, number]);
+    /**
+     * @description 是否正在编辑关键属性
+     * @deprecated 该属性即将废弃，使用 isCoreEditable 代替
+     */
+    get keyPropertyEditing(): boolean;
+    set keyPropertyEditing(value: boolean);
+    /**
+     * @description 转换为 EffectsCreateInfo
+     * @param withParent 是否包含父节点ID
+     */
+    toCreateInfo(withParent?: boolean): EffectsCreateInfo;
+    /**
+     * @description 克隆 SDKItem
+     */
+    clone(): EffectsItem;
+}
+/**
+ * @description 类型守卫：检查是否是 EffectsItem
+ */
+export declare function isEffectsItem(obj: any): obj is EffectsItem;