@vvfx/sdk 0.1.19-alpha.36 → 0.1.19-alpha.38

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,57 @@
+import type { CardItemProperty, CardCreateInfo, CardHTMLContent } 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 htmlContent(): CardHTMLContent | undefined;
+    set htmlContent(value: CardHTMLContent | 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 转换为 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;

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

@@ -0,0 +1,112 @@
+import type { FrameCreateInfo, LayoutInfo } from '../types';
+import { FrameItemProperty, FrameLayoutMode } from '../types';
+import { SDKItemType, FrameItemOptions } from './types';
+import { BaseItem } from './base-item';
+/**
+ * @description 画板/框架元素 SDKItem 类
+ * @description 支持自动布局和自由布局两种模式
+ * @description 底层以 composition 形式渲染
+ */
+export declare class FrameItem extends BaseItem {
+    /**
+     * @description 元素类型
+     */
+    readonly type = SDKItemType.FRAME;
+    /**
+     * @description 预合成元素ID
+     */
+    subCompositionItemId: string;
+    /**
+     * @description 元素属性
+     */
+    property: FrameItemProperty;
+    constructor(options: FrameItemOptions);
+    /**
+     * @description 子元素ID列表（只读）
+     */
+    get children(): readonly string[];
+    /**
+     * @description 布局模式
+     */
+    get layoutMode(): FrameLayoutMode;
+    set layoutMode(value: FrameLayoutMode);
+    /**
+     * @description 布局信息
+     */
+    get layoutInfos(): Record<string, LayoutInfo> | undefined;
+    set layoutInfos(info: Record<string, LayoutInfo> | 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 scale(): [number, number];
+    set scale(value: [number, 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 添加子元素
+     * @param itemId 子元素ID
+     * @returns 是否添加成功
+     */
+    addChild(itemId: string): boolean;
+    /**
+     * @description 批量添加子元素
+     * @param itemIds 子元素ID列表
+     */
+    addChildren(itemIds: string[]): void;
+    /**
+     * @description 移除子元素
+     * @param itemId 子元素ID
+     * @returns 是否移除成功
+     */
+    removeChild(itemId: string): boolean;
+    /**
+     * @description 批量移除子元素
+     * @param itemIds 子元素ID列表
+     */
+    removeChildren(itemIds: string[]): void;
+    /**
+     * @description 是否包含指定子元素
+     * @param itemId 子元素ID
+     */
+    hasChild(itemId: string): boolean;
+    /**
+     * @description 清空所有子元素
+     */
+    clearChildren(): void;
+    /**
+     * @description 转换为 FrameCreateInfo
+     * @param withParent 是否包含父节点ID
+     */
+    toCreateInfo(withParent?: boolean): FrameCreateInfo;
+    /**
+     * @description 克隆 SDKItem
+     */
+    clone(): FrameItem;
+}
+/**
+ * @description 类型守卫：检查是否是 FrameItem
+ */
+export declare function isFrameItem(obj: any): obj is FrameItem;

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

@@ -0,0 +1,86 @@
+import type { GeneratorItemProperty, GeneratorCreateInfo, VideoCreateInfo, SpriteCreateInfo } from '../types';
+import { SDKItemType, GeneratorItemOptions } from './types';
+import { BaseItem } from './base-item';
+/**
+ * @description 资源生成器元素 SDKItem 类
+ * @description 支持 image 和 video 两种生成器类型
+ * @description 在 Player 中以透明 SpriteItem 形式渲染
+ * @description 支持属性扩展，可转换为 SpriteItem 或 VideoItem
+ */
+export declare class GeneratorItem extends BaseItem {
+    /**
+     * @description 元素类型（独立类型，不属于 spec.ItemType）
+     */
+    readonly type = SDKItemType.GENERATOR;
+    /**
+     * @description 元素属性（包含 generatorType）
+     */
+    property: GeneratorItemProperty;
+    constructor(options: GeneratorItemOptions);
+    /**
+     * @description 生成器类型
+     */
+    get generatorType(): 'image' | 'video';
+    set generatorType(value: 'image' | 'video');
+    /**
+     * @description 图片地址（生成器返回空）
+     */
+    get image(): string;
+    set image(_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 转换为 GeneratorCreateInfo
+     * @param withParent 是否包含父节点ID
+     */
+    toCreateInfo(withParent?: boolean): GeneratorCreateInfo;
+    /**
+     * @description 转换为 VideoCreateInfo（用于转换为视频元素）
+     * @param videoUrl 视频资源地址
+     * @param withParent 是否包含父节点ID
+     */
+    toVideoCreateInfo(videoUrl: string, withParent?: boolean): VideoCreateInfo;
+    /**
+     * @description 转换为 SpriteCreateInfo（用于转换为图片元素）
+     * @param imageUrl 图片资源地址
+     * @param withParent 是否包含父节点ID
+     */
+    toSpriteCreateInfo(imageUrl: string, withParent?: boolean): SpriteCreateInfo;
+    /**
+     * @description 克隆 SDKItem
+     */
+    clone(): GeneratorItem;
+}
+/**
+ * @description 类型守卫：检查是否是 GeneratorItem
+ */
+export declare function isGeneratorItem(obj: any): obj is GeneratorItem;