@eva/plugin-matterjs 2.0.1-beta.27 → 2.0.1-beta.28

package/dist/plugin-matterjs.cjs.js

@@ -10864,10 +10864,39 @@ exports.PhysicsType = void 0;
     PhysicsType["CIRCLE"] = "circle";
     PhysicsType["POLYGON"] = "polygon";
 })(exports.PhysicsType || (exports.PhysicsType = {}));
+/**
+ * 物理组件
+ *
+ * Physics 组件为游戏对象提供 Matter.js 物理引擎支持。
+ * 可以创建不同类型的刚体（矩形、圆形、多边形），
+ * 并自动同步物理引擎的位置和旋转到游戏对象的 Transform。
+ *
+ * @example
+ * ```typescript
+ * const ball = new GameObject('ball');
+ * ball.addComponent(new Physics({
+ *   type: PhysicsType.CIRCLE,
+ *   radius: 25,
+ *   bodyOptions: {
+ *     restitution: 0.8, // 弹性
+ *     density: 0.01 // 密度
+ *   }
+ * }));
+ * ```
+ */
 class Physics extends eva_js.Component {
+    /**
+     * 初始化物理组件
+     * @param params - 物理体参数
+     */
     init(params) {
         this.bodyParams = params;
     }
+    /**
+     * 每帧更新物理状态
+     *
+     * 将物理引擎计算的位置和旋转同步到游戏对象的 Transform 组件。
+     */
     update() {
         if (this.body && this.gameObject) {
             this.gameObject.transform.anchor.x = 0;
@@ -10879,10 +10908,16 @@ class Physics extends eva_js.Component {
             }
         }
     }
+    /**
+     * 组件销毁时调用
+     *
+     * 从物理世界中移除物理体。
+     */
     onDestroy() {
         Matter$1.World.remove(this.PhysicsEngine.world, this.body, true);
     }
 }
+/** 组件名称 */
 Physics.componentName = 'Physics';
 
 class BodiesFactory {
@@ -10938,6 +10973,7 @@ class PhysicsEngine {
         this.options = options;
         this.runner = this.Runner.create({
             fps: this.options.fps || 60,
+            // Eva.js设置fps30也可能导致deltaTime为16，导致经过matterjs采样后的一段时间的delta都是很低
             deltaSampleSize: this.options.deltaSampleSize || 1,
         });
     }
@@ -10968,6 +11004,7 @@ class PhysicsEngine {
     }
     update(e) {
         if (!this.options.isTest) {
+            // @ts-ignore
             this.Runner.tick(this.runner, this.engine, e.currentTime);
         }
     }
@@ -11046,15 +11083,82 @@ class PhysicsEngine {
     }
 }
 
+/**
+ * 物理系统（基于 Matter.js）
+ *
+ * PhysicsSystem 集成了 Matter.js 2D 物理引擎，为游戏提供完整的刚体物理模拟。
+ * 它管理物理世界、物理引擎的运行，并自动同步物理引擎的状态到游戏对象。
+ *
+ * 主要功能：
+ * - 集成 Matter.js 物理引擎
+ * - 管理物理世界和物理体
+ * - 自动同步物理状态到游戏对象
+ * - 支持鼠标交互约束
+ * - 可配置物理引擎参数和渲染调试
+ *
+ * @example
+ * ```typescript
+ * // 基础配置
+ * game.addSystem(new PhysicsSystem({
+ *   resolution: 2,
+ *   fps: 60,
+ *   world: {
+ *     gravity: { x: 0, y: 1 } // 重力方向
+ *   }
+ * }));
+ *
+ * // 开启调试渲染和鼠标交互
+ * game.addSystem(new PhysicsSystem({
+ *   isTest: true, // 显示物理调试绘制
+ *   canvas: debugCanvas,
+ *   mouse: {
+ *     open: true // 启用鼠标拖拽物理体
+ *   },
+ *   world: {
+ *     gravity: { x: 0, y: 1 }
+ *   }
+ * }));
+ * ```
+ */
 let PhysicsSystem = class PhysicsSystem extends eva_js.System {
+    /**
+     * 初始化物理系统
+     *
+     * 配置物理引擎参数、创建物理世界、设置渲染分辨率等。
+     *
+     * @param param - 物理系统配置参数
+     * @param param.resolution - 渲染分辨率，默认 1
+     * @param param.fps - 物理引擎更新帧率，默认 60
+     * @param param.isTest - 是否开启调试渲染模式
+     * @param param.element - 物理调试渲染的容器元素
+     * @param param.canvas - 物理调试渲染的画布
+     * @param param.deltaSampleSize - 时间步长采样大小
+     * @param param.mouse - 鼠标交互配置
+     * @param param.world - Matter.js 世界配置（重力、边界等）
+     */
     init(param) {
         this.engine = new PhysicsEngine(this.game, param);
         this.game.canvas.setAttribute('data-pixel-ratio', (param.resolution || '1'));
     }
+    /**
+     * System 被安装的时候，如果游戏还没有开始，那么会在游戏开始的时候调用。用于前置操作，初始化数据等。
+     *
+     * Called while the System installed, if game is not begain, it will be called while begain. use to pre operation, init data.
+     */
     awake() { }
+    /**
+     * System 被安装后，所有的 awake 执行完后
+     *
+     * Called while the System installed, after all of systems' awake been called
+     */
     start() {
         this.engine.start();
     }
+    /**
+     * 每一次游戏循环调用，可以做一些游戏操作，控制改变一些组件属性。
+     *
+     * Called by every loop, can do some operation, change some property or other component property.
+     */
     update(e) {
         const changes = this.componentObserver.clear();
         for (const changed of changes) {
@@ -11099,17 +11203,37 @@ let PhysicsSystem = class PhysicsSystem extends eva_js.System {
             }
         }
     }
+    /**
+     * 和 update?() 类似，在所有System和组件的 update?() 执行以后调用。
+     *
+     * Like update, called all of gameobject update.
+     */
     lateUpdate() { }
+    /**
+     * 游戏开始和游戏暂停后开始播放的时候调用。
+     *
+     * Called while the game to play when game pause.
+     */
     onResume() {
         if (!this.engine.enabled) {
             this.engine.awake();
         }
     }
+    /**
+     * 游戏暂停的时候调用。
+     *
+     * Called while the game paused.
+     */
     onPause() {
         this.engine.stop();
     }
+    /**
+     * System 被销毁的时候调用。
+     * Called while the system be destroyed.
+     */
     onDestroy() { }
 };
+/** 系统名称 */
 PhysicsSystem.systemName = 'PhysicsSystem';
 PhysicsSystem = __decorate([
     eva_js.decorators.componentObserver({

package/dist/plugin-matterjs.d.ts

@@ -6,13 +6,51 @@ declare type DeepPartial<T> = {
     [P in keyof T]?: T[P] extends Object ? DeepPartial<T[P]> : T[P];
 };
 
+/**
+ * 物理组件
+ *
+ * Physics 组件为游戏对象提供 Matter.js 物理引擎支持。
+ * 可以创建不同类型的刚体（矩形、圆形、多边形），
+ * 并自动同步物理引擎的位置和旋转到游戏对象的 Transform。
+ *
+ * @example
+ * ```typescript
+ * const ball = new GameObject('ball');
+ * ball.addComponent(new Physics({
+ *   type: PhysicsType.CIRCLE,
+ *   radius: 25,
+ *   bodyOptions: {
+ *     restitution: 0.8, // 弹性
+ *     density: 0.01 // 密度
+ *   }
+ * }));
+ * ```
+ */
 export declare class Physics extends Component<PhysicsParams> {
+    /** 组件名称 */
     static componentName: string;
+    /** 物理体参数配置 */
     bodyParams: PhysicsParams;
+    /** Matter.js 物理体实例 */
     body: Matter.Body;
+    /** Matter.js 物理引擎实例 */
     private PhysicsEngine;
+    /**
+     * 初始化物理组件
+     * @param params - 物理体参数
+     */
     init(params: PhysicsParams): void;
+    /**
+     * 每帧更新物理状态
+     *
+     * 将物理引擎计算的位置和旋转同步到游戏对象的 Transform 组件。
+     */
     update(): void;
+    /**
+     * 组件销毁时调用
+     *
+     * 从物理世界中移除物理体。
+     */
     onDestroy(): void;
 }
 
@@ -33,17 +71,105 @@ declare interface PhysicsParams {
     stopRotation?: boolean;
 }
 
+/**
+ * 物理系统（基于 Matter.js）
+ *
+ * PhysicsSystem 集成了 Matter.js 2D 物理引擎，为游戏提供完整的刚体物理模拟。
+ * 它管理物理世界、物理引擎的运行，并自动同步物理引擎的状态到游戏对象。
+ *
+ * 主要功能：
+ * - 集成 Matter.js 物理引擎
+ * - 管理物理世界和物理体
+ * - 自动同步物理状态到游戏对象
+ * - 支持鼠标交互约束
+ * - 可配置物理引擎参数和渲染调试
+ *
+ * @example
+ * ```typescript
+ * // 基础配置
+ * game.addSystem(new PhysicsSystem({
+ *   resolution: 2,
+ *   fps: 60,
+ *   world: {
+ *     gravity: { x: 0, y: 1 } // 重力方向
+ *   }
+ * }));
+ *
+ * // 开启调试渲染和鼠标交互
+ * game.addSystem(new PhysicsSystem({
+ *   isTest: true, // 显示物理调试绘制
+ *   canvas: debugCanvas,
+ *   mouse: {
+ *     open: true // 启用鼠标拖拽物理体
+ *   },
+ *   world: {
+ *     gravity: { x: 0, y: 1 }
+ *   }
+ * }));
+ * ```
+ */
 export declare class PhysicsSystem extends System<PhysicsSystemParams> {
+    /** 系统名称 */
     static systemName: string;
+    /** 物理引擎实例 */
     private engine;
+    /**
+     * 初始化物理系统
+     *
+     * 配置物理引擎参数、创建物理世界、设置渲染分辨率等。
+     *
+     * @param param - 物理系统配置参数
+     * @param param.resolution - 渲染分辨率，默认 1
+     * @param param.fps - 物理引擎更新帧率，默认 60
+     * @param param.isTest - 是否开启调试渲染模式
+     * @param param.element - 物理调试渲染的容器元素
+     * @param param.canvas - 物理调试渲染的画布
+     * @param param.deltaSampleSize - 时间步长采样大小
+     * @param param.mouse - 鼠标交互配置
+     * @param param.world - Matter.js 世界配置（重力、边界等）
+     */
     init(param?: PhysicsSystemParams): void;
+    /**
+     * System 被安装的时候，如果游戏还没有开始，那么会在游戏开始的时候调用。用于前置操作，初始化数据等。
+     *
+     * Called while the System installed, if game is not begain, it will be called while begain. use to pre operation, init data.
+     */
     awake(): void;
+    /**
+     * System 被安装后，所有的 awake 执行完后
+     *
+     * Called while the System installed, after all of systems' awake been called
+     */
     start(): void;
+    /**
+     * 每一次游戏循环调用，可以做一些游戏操作，控制改变一些组件属性。
+     *
+     * Called by every loop, can do some operation, change some property or other component property.
+     */
     update(e: any): void;
     componentChanged(changed: ComponentChanged): void;
+    /**
+     * 和 update?() 类似，在所有System和组件的 update?() 执行以后调用。
+     *
+     * Like update, called all of gameobject update.
+     */
     lateUpdate(): void;
+    /**
+     * 游戏开始和游戏暂停后开始播放的时候调用。
+     *
+     * Called while the game to play when game pause.
+     */
     onResume(): void;
+    /**
+     * 游戏暂停的时候调用。
+     *
+     * Called while the game paused.
+     */
     onPause(): void;
+    /**
+     * System 被销毁的时候调用。
+     * Called while the system be destroyed.
+     */
     onDestroy(): void;
 }
 

package/dist/plugin-matterjs.esm.js

@@ -10860,10 +10860,39 @@ var PhysicsType;
     PhysicsType["CIRCLE"] = "circle";
     PhysicsType["POLYGON"] = "polygon";
 })(PhysicsType || (PhysicsType = {}));
+/**
+ * 物理组件
+ *
+ * Physics 组件为游戏对象提供 Matter.js 物理引擎支持。
+ * 可以创建不同类型的刚体（矩形、圆形、多边形），
+ * 并自动同步物理引擎的位置和旋转到游戏对象的 Transform。
+ *
+ * @example
+ * ```typescript
+ * const ball = new GameObject('ball');
+ * ball.addComponent(new Physics({
+ *   type: PhysicsType.CIRCLE,
+ *   radius: 25,
+ *   bodyOptions: {
+ *     restitution: 0.8, // 弹性
+ *     density: 0.01 // 密度
+ *   }
+ * }));
+ * ```
+ */
 class Physics extends Component {
+    /**
+     * 初始化物理组件
+     * @param params - 物理体参数
+     */
     init(params) {
         this.bodyParams = params;
     }
+    /**
+     * 每帧更新物理状态
+     *
+     * 将物理引擎计算的位置和旋转同步到游戏对象的 Transform 组件。
+     */
     update() {
         if (this.body && this.gameObject) {
             this.gameObject.transform.anchor.x = 0;
@@ -10875,10 +10904,16 @@ class Physics extends Component {
             }
         }
     }
+    /**
+     * 组件销毁时调用
+     *
+     * 从物理世界中移除物理体。
+     */
     onDestroy() {
         Matter$1.World.remove(this.PhysicsEngine.world, this.body, true);
     }
 }
+/** 组件名称 */
 Physics.componentName = 'Physics';
 
 class BodiesFactory {
@@ -10934,6 +10969,7 @@ class PhysicsEngine {
         this.options = options;
         this.runner = this.Runner.create({
             fps: this.options.fps || 60,
+            // Eva.js设置fps30也可能导致deltaTime为16，导致经过matterjs采样后的一段时间的delta都是很低
             deltaSampleSize: this.options.deltaSampleSize || 1,
         });
     }
@@ -10964,6 +11000,7 @@ class PhysicsEngine {
     }
     update(e) {
         if (!this.options.isTest) {
+            // @ts-ignore
             this.Runner.tick(this.runner, this.engine, e.currentTime);
         }
     }
@@ -11042,15 +11079,82 @@ class PhysicsEngine {
     }
 }
 
+/**
+ * 物理系统（基于 Matter.js）
+ *
+ * PhysicsSystem 集成了 Matter.js 2D 物理引擎，为游戏提供完整的刚体物理模拟。
+ * 它管理物理世界、物理引擎的运行，并自动同步物理引擎的状态到游戏对象。
+ *
+ * 主要功能：
+ * - 集成 Matter.js 物理引擎
+ * - 管理物理世界和物理体
+ * - 自动同步物理状态到游戏对象
+ * - 支持鼠标交互约束
+ * - 可配置物理引擎参数和渲染调试
+ *
+ * @example
+ * ```typescript
+ * // 基础配置
+ * game.addSystem(new PhysicsSystem({
+ *   resolution: 2,
+ *   fps: 60,
+ *   world: {
+ *     gravity: { x: 0, y: 1 } // 重力方向
+ *   }
+ * }));
+ *
+ * // 开启调试渲染和鼠标交互
+ * game.addSystem(new PhysicsSystem({
+ *   isTest: true, // 显示物理调试绘制
+ *   canvas: debugCanvas,
+ *   mouse: {
+ *     open: true // 启用鼠标拖拽物理体
+ *   },
+ *   world: {
+ *     gravity: { x: 0, y: 1 }
+ *   }
+ * }));
+ * ```
+ */
 let PhysicsSystem = class PhysicsSystem extends System {
+    /**
+     * 初始化物理系统
+     *
+     * 配置物理引擎参数、创建物理世界、设置渲染分辨率等。
+     *
+     * @param param - 物理系统配置参数
+     * @param param.resolution - 渲染分辨率，默认 1
+     * @param param.fps - 物理引擎更新帧率，默认 60
+     * @param param.isTest - 是否开启调试渲染模式
+     * @param param.element - 物理调试渲染的容器元素
+     * @param param.canvas - 物理调试渲染的画布
+     * @param param.deltaSampleSize - 时间步长采样大小
+     * @param param.mouse - 鼠标交互配置
+     * @param param.world - Matter.js 世界配置（重力、边界等）
+     */
     init(param) {
         this.engine = new PhysicsEngine(this.game, param);
         this.game.canvas.setAttribute('data-pixel-ratio', (param.resolution || '1'));
     }
+    /**
+     * System 被安装的时候，如果游戏还没有开始，那么会在游戏开始的时候调用。用于前置操作，初始化数据等。
+     *
+     * Called while the System installed, if game is not begain, it will be called while begain. use to pre operation, init data.
+     */
     awake() { }
+    /**
+     * System 被安装后，所有的 awake 执行完后
+     *
+     * Called while the System installed, after all of systems' awake been called
+     */
     start() {
         this.engine.start();
     }
+    /**
+     * 每一次游戏循环调用，可以做一些游戏操作，控制改变一些组件属性。
+     *
+     * Called by every loop, can do some operation, change some property or other component property.
+     */
     update(e) {
         const changes = this.componentObserver.clear();
         for (const changed of changes) {
@@ -11095,17 +11199,37 @@ let PhysicsSystem = class PhysicsSystem extends System {
             }
         }
     }
+    /**
+     * 和 update?() 类似，在所有System和组件的 update?() 执行以后调用。
+     *
+     * Like update, called all of gameobject update.
+     */
     lateUpdate() { }
+    /**
+     * 游戏开始和游戏暂停后开始播放的时候调用。
+     *
+     * Called while the game to play when game pause.
+     */
     onResume() {
         if (!this.engine.enabled) {
             this.engine.awake();
         }
     }
+    /**
+     * 游戏暂停的时候调用。
+     *
+     * Called while the game paused.
+     */
     onPause() {
         this.engine.stop();
     }
+    /**
+     * System 被销毁的时候调用。
+     * Called while the system be destroyed.
+     */
     onDestroy() { }
 };
+/** 系统名称 */
 PhysicsSystem.systemName = 'PhysicsSystem';
 PhysicsSystem = __decorate([
     decorators.componentObserver({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eva/plugin-matterjs",
-  "version": "2.0.1-beta.27",
+  "version": "2.0.1-beta.28",
   "description": "@eva/plugin-matterjs",
   "main": "index.js",
   "module": "dist/plugin-matterjs.esm.js",
@@ -18,7 +18,7 @@
   "license": "MIT",
   "homepage": "https://eva.js.org",
   "dependencies": {
-    "@eva/eva.js": "2.0.1-beta.27",
+    "@eva/eva.js": "2.0.1-beta.28",
     "@types/matter-js": "^0.17.5",
     "poly-decomp": "^0.3.0"
   }