@vvfx/sdk 0.2.8 → 0.2.9

package/dist/math/vector3.js

@@ -0,0 +1,60 @@
+import { math } from '../shared';
+import { Quaternion } from './quaternion';
+export class Vector3 extends math.Vector3 {
+    clone() {
+        return new Vector3(this.x, this.y, this.z);
+    }
+    /**
+     * 由空间变换矩阵保存三维分量
+     * @param {Matrix4} m 四维矩阵
+     * @param {number} index 下标
+     * @returns {Vec3} 指定三维分量
+     */
+    setFromMatrixColumn(m, index) {
+        // 这里断言了，类型不安全，之后加 lint，必须有明显的 disable lint 起提示作用
+        return this.set(...m.elements.slice(index * 4));
+    }
+    applyEuler(euler, _out) {
+        return this.applyQuaternion(new Quaternion().setFromEuler(euler));
+    }
+    /**
+     * 三维点根据四元数绕点的旋转
+     * @param {Quaternion} q 四元数
+     * @param {Vec3} [center=new Vec3()] 旋转中心
+     * @returns {Vec3} 旋转结果
+     */
+    applyQuaternion(q, center = new Vector3()) {
+        const { x: qx, y: qy, z: qz, w: qw } = q;
+        const { x: vx, y: vy, z: vz } = this.subtract(center);
+        const ix = qw * vx + qy * vz - qz * vy;
+        const iy = qw * vy + qz * vx - qx * vz;
+        const iz = qw * vz + qx * vy - qy * vx;
+        const iw = -qx * vx - qy * vy - qz * vz;
+        this.x = ix * qw + iw * -qx + iy * -qz - iz * -qy + center.x;
+        this.y = iy * qw + iw * -qy + iz * -qx - ix * -qz + center.y;
+        this.z = iz * qw + iw * -qz + ix * -qy - iy * -qx + center.z;
+        return this;
+    }
+    /**
+     * 由空间变换矩阵保存三维偏移值
+     * @param {Matrix4} m 四维矩阵
+     * @returns {Vec3} 偏移值
+     */
+    setFromMatrixPosition(m) {
+        const e = m.elements;
+        this.x = e[12];
+        this.y = e[13];
+        this.z = e[14];
+        return this;
+    }
+    applyMatrix(matrix, center = new Vector3()) {
+        const e = matrix.elements;
+        const { x: vx, y: vy, z: vz } = this.subtract(center);
+        let w = 1 / (e[3] * vx + e[7] * vy + e[11] * vz + e[15]);
+        w = isNaN(w) ? 1 : w;
+        this.x = (e[0] * vx + e[4] * vy + e[8] * vz + e[12]) * w + center.x;
+        this.y = (e[1] * vx + e[5] * vy + e[9] * vz + e[13]) * w + center.y;
+        this.z = (e[2] * vx + e[6] * vy + e[10] * vz + e[14]) * w + center.z;
+        return this;
+    }
+}

package/dist/screen-shot/index.js

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

package/dist/screen-shot/screen-shot.js

@@ -0,0 +1,113 @@
+import { clamp } from '../math';
+import { Player } from '../shared';
+import { clearPlayerAssets } from '../exporter/utils';
+import { SDK } from '../sdk';
+/**
+ * @description 截图工具
+ */
+export class ScreenShot {
+    /**
+     * @description 功能开关
+     */
+    enabled = true;
+    /**
+     * @description 截图播放器
+     */
+    _player;
+    /**
+     * @description 截图播放器容器
+     */
+    _container;
+    constructor() {
+        this._container = document.createElement('canvas');
+        this._player = new Player({
+            canvas: this._container,
+            manualRender: true,
+            pixelRatio: 2,
+            env: 'editor',
+            renderOptions: {
+                willCaptureImage: true,
+            },
+        });
+    }
+    /**
+     * @description 生成截图
+     * @param scene 场景数据
+     * @param resultSize 截图大小
+     * @param tick 截图时刻
+     * @param screenArea 截图范围【可选】 - [左上角x坐标， 左上角y坐标， 截图宽度， 截图高度]
+     * @returns 截图base64数据
+     */
+    async generate(scene, containerSize, resultSize, tick, background) {
+        if (!SDK.config.screenShotConfig.enabled) {
+            console.warn('Screen shot is not opened, use #SDK.setConfig() open this feature.');
+            return;
+        }
+        clearPlayerAssets(this._player);
+        const [containerWidth, containerHieght] = containerSize;
+        this._container.width = containerWidth;
+        this._container.height = containerHieght;
+        this._player.resize();
+        const resultScene = typeof scene === 'string' ? scene : JSON.parse(JSON.stringify(scene));
+        await this._player.loadScene(resultScene);
+        this._player.gotoAndStop(tick);
+        const [width, height] = resultSize;
+        const result = document.createElement('canvas');
+        result.width = width;
+        result.height = height;
+        const ctx = result.getContext('2d');
+        background ??= SDK.config.screenShotConfig.defaultBackgroundColor;
+        if (ctx) {
+            ctx.fillStyle = `rgba(${background.join(',')})`;
+            ctx.fillRect(0, 0, width, height);
+            this.drawImageCover(ctx, this._player.canvas, 0, 0, width, height, 0.5, 0.5);
+        }
+        const thumbnail = result.toDataURL('image/png');
+        clearPlayerAssets(this._player);
+        return thumbnail;
+    }
+    dispose() {
+        this._player.dispose();
+    }
+    drawImageCover(ctx, img, x, y, w, h, offsetX, offsetY, sourceRect) {
+        if (arguments.length === 2) {
+            x = y = 0;
+            w = ctx.canvas.width;
+            h = ctx.canvas.height;
+        }
+        // default offset is center
+        offsetX = typeof offsetX === 'number' ? clamp(offsetX, 0, 1) : 0.5;
+        offsetY = typeof offsetY === 'number' ? clamp(offsetY, 0, 1) : 0.5;
+        // keep bounds [0.0, 1.0]
+        // if (offsetX < 0) { offsetX = 0 }
+        // if (offsetY < 0) { offsetY = 0 }
+        // if (offsetX > 1) { offsetX = 1 }
+        // if (offsetY > 1) { offsetY = 1 }
+        sourceRect ??= {
+            left: 0,
+            top: 0,
+            width: img instanceof HTMLVideoElement ? img.videoWidth : img.width,
+            height: img instanceof HTMLVideoElement ? img.videoHeight : img.height,
+        };
+        const iw = sourceRect.width, ih = sourceRect.height, r = Math.min(w / iw, h / ih);
+        let nw = iw * r, // new prop. width
+        nh = ih * r, // new prop. height
+        ar = 1;
+        // decide which gap to fill
+        if (nw < w) {
+            ar = w / nw;
+        }
+        if (Math.abs(ar - 1) < 1e-14 && nh < h) {
+            ar = h / nh;
+        } // updated
+        nw *= ar;
+        nh *= ar;
+        // calc source rectangle
+        const cw = Math.max(iw / (nw / w), 0);
+        const ch = Math.max(ih / (nh / h), 0);
+        const cx = Math.min((iw - cw) * offsetX, iw);
+        const cy = Math.min((ih - ch) * offsetY, ih);
+        // fill image in dest. rectangle
+        ctx.drawImage(img, cx + sourceRect.left, cy + sourceRect.top, cw, ch, x, y, w, h);
+    }
+}

package/dist/sdk-item/base-item.js

@@ -0,0 +1,160 @@
+import { spec } from '../shared';
+import { deepClone } from '../utils/common-utils';
+/**
+ * @description SDKItem 抽象基类
+ * @description 支持属性扩展，允许添加任意自定义属性
+ */
+export class BaseItem {
+    /**
+     * @description 元素ID
+     */
+    id;
+    /**
+     * @description 元素名称
+     */
+    name;
+    /**
+     * @description 父节点ID
+     */
+    parentId;
+    /**
+     * @description 元素生命周期
+     */
+    duration;
+    /**
+     * @description 元素生命周期延时
+     */
+    delay;
+    /**
+     * @description 元素结束行为
+     */
+    endBehavior;
+    /**
+     * @description 是否可见
+     */
+    visible;
+    /**
+     * @description 是否处于锁定状态
+     */
+    isLocked;
+    /**
+     * @description 核心数据是否支持编辑
+     */
+    isCoreEditable;
+    /**
+     * @description 扩展属性存储（与 property 同级）
+     */
+    extension = new Map();
+    constructor(options) {
+        this.id = options.id;
+        this.name = options.name;
+        this.parentId = options.parentId;
+        this.duration = options.duration ?? 999;
+        this.delay = options.delay ?? 0;
+        this.endBehavior = options.endBehavior ?? spec.EndBehavior.freeze;
+        this.visible = options.visible ?? true;
+        this.isLocked = options.isLocked ?? false;
+        this.isCoreEditable = options.isCoreEditable;
+        // 处理显式扩展属性
+        if (options.extension) {
+            Object.entries(options.extension).forEach(([key, value]) => {
+                this.extension.set(key, value);
+            });
+        }
+    }
+    get pixelWidth() {
+        return this.property.width * (this.property.scale?.[0] ?? 1);
+    }
+    get pixelHeight() {
+        return this.property.height * (this.property.scale?.[1] ?? 1);
+    }
+    // ==================== 扩展属性支持 ====================
+    /**
+     * @description 设置扩展属性
+     * @param key 属性名
+     * @param value 属性值
+     */
+    setExtension(key, value) {
+        this.extension.set(key, value);
+    }
+    /**
+     * @description 获取扩展属性
+     * @param key 属性名
+     * @returns 属性值
+     */
+    getExtension(key) {
+        return this.extension.get(key);
+    }
+    /**
+     * @description 检查是否存在指定扩展属性
+     * @param key 属性名
+     * @returns 是否存在
+     */
+    hasExtension(key) {
+        return this.extension.has(key);
+    }
+    /**
+     * @description 删除扩展属性
+     * @param key 属性名
+     * @returns 是否删除成功
+     */
+    deleteExtension(key) {
+        return this.extension.delete(key);
+    }
+    /**
+     * @description 获取所有扩展属性的键名列表
+     * @returns 键名数组
+     */
+    getExtensionKeys() {
+        return Array.from(this.extension.keys());
+    }
+    /**
+     * @description 获取所有扩展属性
+     * @returns 扩展属性对象
+     */
+    getAllExtension() {
+        return deepClone(Object.fromEntries(this.extension.entries()));
+    }
+    /**
+     * @description 批量设置扩展属性
+     * @param extensions 扩展属性对象
+     */
+    setExtensions(extensions) {
+        Object.entries(extensions).forEach(([key, value]) => {
+            this.extension.set(key, value);
+        });
+    }
+    /**
+     * @description 清空所有扩展属性
+     */
+    clearExtension() {
+        this.extension.clear();
+    }
+    // ==================== 通用方法 ====================
+    /**
+     * @description 获取基础属性的 JSON 对象,转换为普通对象（用于序列化）
+     * @returns 普通对象
+     */
+    toJSON() {
+        return {
+            id: this.id,
+            name: this.name,
+            type: this.type,
+            parentId: this.parentId,
+            duration: this.duration,
+            delay: this.delay,
+            endBehavior: this.endBehavior,
+            isLocked: this.isLocked,
+            property: deepClone(this.property),
+            extension: this.getAllExtension()
+        };
+    }
+}
+/**
+ * @description 类型守卫函数：检查对象是否是 BaseItem
+ * @param obj 要检查的对象
+ * @returns 是否是 BaseItem 实例
+ */
+export function isBaseItem(obj) {
+    return obj instanceof BaseItem;
+}

package/dist/sdk-item/card-item.js

@@ -0,0 +1,131 @@
+import { SDKItemType } from './types';
+import { BaseItem } from './base-item';
+import { deepClone } from '../utils/common-utils';
+import { generateGUID } from '../shared';
+import { SDK } from '../sdk';
+/**
+ * @description 卡片元素 SDKItem 类
+ * @description 在 Player 中以 SpriteItem 形式渲染（透明占位，无图）
+ * @description 支持设置卡片类型（cardType）
+ */
+export class CardItem extends BaseItem {
+    /**
+     * @description 元素类型
+     */
+    type = SDKItemType.CARD;
+    /**
+     * @description 元素属性（包含 cardType）
+     */
+    property;
+    constructor(options) {
+        super(options);
+        // 初始化属性（包含 cardType）
+        this.property = {
+            position: options.property?.position ?? [0, 0],
+            rotation: options.property?.rotation ?? [0, 0, 0],
+            width: options.property?.width ?? 0,
+            height: options.property?.height ?? 0,
+            scale: options.property?.scale ?? [1, 1],
+            cardType: options.property?.cardType ?? 'unknown',
+        };
+    }
+    // ==================== cardType 访问器 ====================
+    /**
+     * @description 卡片类型
+     */
+    get cardType() {
+        return this.property.cardType;
+    }
+    set cardType(value) {
+        this.property.cardType = value;
+    }
+    // ==================== 便捷访问器 ====================
+    /**
+     * @description 位置
+     */
+    get position() {
+        return this.property.position;
+    }
+    set position(value) {
+        this.property.position = value;
+    }
+    get isAutoScale() {
+        const config = SDK.config.itemConfig.cardConfig.cardTypes.find(t => t.type === this.cardType);
+        return config?.autoScale !== false;
+    }
+    /**
+     * @description 宽度
+     */
+    get width() {
+        return this.property.width;
+    }
+    set width(value) {
+        this.property.width = value;
+    }
+    /**
+     * @description 高度
+     */
+    get height() {
+        return this.property.height;
+    }
+    set height(value) {
+        this.property.height = value;
+    }
+    /**
+     * @description 旋转（二维旋转角度）
+     */
+    get rotation() {
+        return this.property.rotation[2];
+    }
+    set rotation(value) {
+        this.property.rotation[2] = value;
+    }
+    /**
+     * @description 完整旋转（包含 x, y, z）
+     */
+    get fullRotation() {
+        return this.property.rotation;
+    }
+    set fullRotation(value) {
+        this.property.rotation = value;
+    }
+    // ==================== 实现抽象方法 ====================
+    /**
+     * @description 转换为 CardCreateInfo
+     * @param withParent 是否包含父节点ID
+     */
+    toCreateInfo(withParent) {
+        const extension = this.getAllExtension();
+        return {
+            type: SDKItemType.CARD,
+            id: this.id,
+            name: this.name,
+            parentId: withParent ? this.parentId : undefined,
+            extension: Object.keys(extension).length > 0 ? extension : undefined,
+            property: deepClone(this.property)
+        };
+    }
+    /**
+     * @description 克隆 SDKItem
+     */
+    clone() {
+        return new CardItem({
+            id: generateGUID(),
+            name: this.name,
+            parentId: this.parentId,
+            duration: this.duration,
+            delay: this.delay,
+            endBehavior: this.endBehavior,
+            isLocked: this.isLocked,
+            isCoreEditable: this.isCoreEditable,
+            property: deepClone(this.property),
+            extension: this.getAllExtension()
+        });
+    }
+}
+/**
+ * @description 类型守卫：检查是否是 CardItem
+ */
+export function isCardItem(obj) {
+    return obj instanceof CardItem;
+}

package/dist/sdk-item/effects-item.js

@@ -0,0 +1,144 @@
+import { SDKItemType } from './types';
+import { BaseItem } from './base-item';
+import { deepClone } from '../utils/common-utils';
+import { generateGUID } from '../shared';
+/**
+ * @description 特效产物 元素 SDKItem 类
+ */
+export class EffectsItem extends BaseItem {
+    /**
+     * @description 元素类型（独立类型，不属于 spec.ItemType）
+     */
+    type = SDKItemType.EFFECTS;
+    /**
+     * @description 预合成元素ID
+     */
+    subCompositionItemId;
+    /**
+     * @description 元素属性
+     */
+    property;
+    constructor(options) {
+        super(options);
+        this.subCompositionItemId = '';
+        this.property = {
+            position: options.property?.position ?? [0, 0],
+            rotation: options.property?.rotation ?? [0, 0, 0],
+            width: options.property?.width ?? 0,
+            height: options.property?.height ?? 0,
+            scale: options.property?.scale ?? [1, 1],
+            effects: options.property?.effects ?? '',
+            children: options.property?.children ?? []
+        };
+    }
+    // ==================== 便捷访问器 ====================
+    /**
+     * @description 特效资源地址
+     */
+    get effects() {
+        return this.property.effects;
+    }
+    set effects(value) {
+        this.property.effects = value;
+    }
+    /**
+     * @description 位置
+     */
+    get position() {
+        return this.property.position;
+    }
+    set position(value) {
+        this.property.position = value;
+    }
+    /**
+     * @description 宽度
+     */
+    get width() {
+        return this.property.width;
+    }
+    set width(value) {
+        this.property.width = value;
+    }
+    /**
+     * @description 高度
+     */
+    get height() {
+        return this.property.height;
+    }
+    set height(value) {
+        this.property.height = value;
+    }
+    /**
+     * @description 旋转（二维旋转角度）
+     */
+    get rotation() {
+        return this.property.rotation[2];
+    }
+    set rotation(value) {
+        this.property.rotation[2] = value;
+    }
+    /**
+     * @description 完整旋转（包含 x, y, z）
+     */
+    get fullRotation() {
+        return this.property.rotation;
+    }
+    set fullRotation(value) {
+        this.property.rotation = value;
+    }
+    /**
+     * @description 是否正在编辑关键属性
+     * @deprecated 该属性即将废弃，使用 isCoreEditable 代替
+     */
+    get keyPropertyEditing() {
+        return this.isCoreEditable;
+    }
+    set keyPropertyEditing(value) {
+        this.isCoreEditable = value;
+    }
+    // ==================== 实现抽象方法 ====================
+    /**
+     * @description 转换为 EffectsCreateInfo
+     * @param withParent 是否包含父节点ID
+     */
+    toCreateInfo(withParent) {
+        const createInfo = {
+            type: SDKItemType.EFFECTS,
+            id: this.id,
+            name: this.name,
+            property: deepClone(this.property)
+        };
+        if (withParent && this.parentId) {
+            createInfo.parentId = this.parentId;
+        }
+        // 添加扩展属性
+        const extension = this.getAllExtension();
+        if (Object.keys(extension).length > 0) {
+            createInfo.extension = extension;
+        }
+        return createInfo;
+    }
+    /**
+     * @description 克隆 SDKItem
+     */
+    clone() {
+        return new EffectsItem({
+            id: generateGUID(),
+            name: this.name,
+            parentId: this.parentId,
+            duration: this.duration,
+            delay: this.delay,
+            endBehavior: this.endBehavior,
+            isLocked: this.isLocked,
+            isCoreEditable: this.isCoreEditable,
+            property: deepClone(this.property),
+            extension: this.getAllExtension()
+        });
+    }
+}
+/**
+ * @description 类型守卫：检查是否是 EffectsItem
+ */
+export function isEffectsItem(obj) {
+    return obj instanceof EffectsItem;
+}