更改示例及新增注释

.fleet/settings.json

@@ -0,0 +1,3 @@
+{
+    "toolchains": []
+}

docs/getting_start.md

@@ -3,15 +3,19 @@
 ## 初始化框架
 
 ```typescript
-// 参数为false则开启debug模式
+// 创建调试模式下的`Core`实例
-es.Core.create(false);
+const core = es.Core.create();
+
+// 创建非调试模式下的`Core`实例
+const core = es.Core.create(false);
 ```
 
 ## 分发帧事件
 
 ```typescript
-// 放置于引擎每帧更新处
+// dt 是一个可选参数，如果传入了 es.Time.deltaTime或者不传入参数，则代表使用框架的内置的时间差来更新游戏状态；
-// dt为可选参数，传入引擎的deltaTime代替框架内的es.Time.deltaTime
+// 如果传入了游戏引擎自带的 deltaTime，则代表使用该值来更新游戏状态。
+// 在 es.Core.update 方法中，会根据 dt 的值来计算时间戳信息，并更新全局管理器和当前场景的状态
 es.Core.emitter.emit(es.CoreEvents.frameUpdated, dt);
 ```
 
@@ -24,35 +28,47 @@ es.Core.emitter.emit(es.CoreEvents.frameUpdated, dt);
 场景类需要继承框架中的 `es.Scene`
 
 ```typescript
-export class MainScene extends es.Scene {
+/** 示例场景 */
-    /**
+export class MainScene extends Scene {
-     * 可重写方法，从contructor中调用这个函数
+    constructor() {
-     */
+        super();
-    initialize() {
-        console.log('initialize');
     }
 
     /**
-     *  可重写方法。当Core将这个场景设置为活动场景时调用
+    * 初始化场景，添加实体和组件
+    *
+    * 这个方法会在场景被创建时被调用。我们在这个方法中创建了一个实体，
+    * 并向它添加了一个SpriteRender组件和一个TransformMove组件。
     */
-    onStart() {
+    public initialize() {
-        console.log('onStart');
+        // 创建一个实体
+        let entity = this.createEntity("Player");
+
+        // 添加一个SpriteRender组件，用于显示实体的图像
+        let spriteRender = entity.addComponent(new SpriteRender());
+        spriteRender.sprite = new es.Sprite(new es.Texture("player.png"));
+
+        // 添加一个TransformMove组件，用于移动实体
+        let transformMove = entity.addComponent(new TransformMove());
+        transformMove.speed = 50;
     }
 
     /**
-     *  可重写方法。当Core把这个场景从活动槽中移除时调用。
+    * 场景开始运行时执行的操作
+    *
+    * 这个方法会在场景开始运行时被调用。我们在这个方法中输出一条消息表示场景已经开始运行。
     */
-    unload() {
+    public onStart() {
-        console.log('unload');
+        console.log("MainScene has started!");
     }
 
     /**
-     * 可重写方法。
+    * 场景被销毁时执行的操作
+    *
+    * 这个方法会在场景被销毁时被调用。我们在这个方法中输出一条消息表示场景已经被卸载。
     */
-    update() {
+    public unload() {
-        // 如果重写update方法 一定要调用该方法
+        console.log("MainScene has been unloaded!");
-        // 不调用将导致实体无法加入/组件无法更新
-        super.update();
     }
 }
 ```

source/bin/framework.d.ts

@@ -57,7 +57,9 @@ declare module es {
         */
         static scene: Scene;
         /**
-         * 默认实现创建核心
+         * `Core`类的静态方法，用于创建`Core`的实例。
+         * @param debug {boolean} 是否为调试模式，默认为`true`
+         * @returns {Core} `Core`的实例
          */
         static create(debug?: boolean): Core;
         /**
@@ -69,12 +71,13 @@ declare module es {
          * 删除全局管理器对象
          * @param manager
          */
-        static unregisterGlobalManager(manager: es.GlobalManager): void;
+        static unregisterGlobalManager(manager: GlobalManager): void;
         /**
-         * 获取类型为T的全局管理器
+         * 获取指定类型的全局管理器实例
-         * @param type
+         * @param type 管理器类型的构造函数
+         * @returns 指定类型的全局管理器实例，如果找不到则返回 null
          */
-        static getGlobalManager<T extends es.GlobalManager>(type: new (...args: any[]) => T): T;
+        static getGlobalManager<T extends GlobalManager>(type: new (...args: any[]) => T): T;
         /**
          * 临时运行SceneTransition，允许一个场景平滑过渡到另一个场景，并具有自定义效果
          * @param sceneTransition
@@ -100,6 +103,10 @@ declare module es {
          */
         onSceneChanged(): void;
         protected initialize(): void;
+        /**
+         * `Core` 类的受保护的 `update` 方法，用于更新游戏状态。
+         * @param currentTime 当前时间戳，单位为毫秒，默认值为-1。
+         */
         protected update(currentTime?: number): void;
         protected draw(): void;
     }
@@ -113,9 +120,31 @@ declare module es {
         trace = 4
     }
     class Debug {
+        /**
+         * 如果条件为true，则在控制台中以警告方式打印消息。
+         * @param condition 是否应该打印消息的条件
+         * @param format 要打印的消息格式
+         * @param args 与消息格式相对应的参数列表
+         */
         static warnIf(condition: boolean, format: string, ...args: any[]): void;
+        /**
+         * 在控制台中以警告方式打印消息。
+         * @param format 要打印的消息格式
+         * @param args 与消息格式相对应的参数列表
+         */
         static warn(format: string, ...args: any[]): void;
+        /**
+         * 在控制台中以错误方式打印消息。
+         * @param format 要打印的消息格式
+         * @param args 与消息格式相对应的参数列表
+         */
         static error(format: string, ...args: any[]): void;
+        /**
+         * 在控制台中以标准日志方式打印消息。
+         * @param type 要打印的日志类型
+         * @param format 要打印的消息格式
+         * @param args 与消息格式相对应的参数列表
+         */
         static log(type: LogType, format: string, ...args: any[]): void;
     }
 }
@@ -713,21 +742,41 @@ declare module es {
         private _didSceneBegin;
         constructor();
         /**
-         * 在场景子类中重写这个，然后在这里进行加载。
+         * 初始化场景，可以在派生类中覆盖
-         * 在场景设置好之后，但在调用begin之前，从contructor中调用这个函数
+         *
+         * 这个方法会在场景创建时被调用。您可以在这个方法中添加实体和组件，
+         * 或者执行一些必要的准备工作，以便场景能够开始运行。
          */
         initialize(): void;
         /**
-         * 当Core将这个场景设置为活动场景时，这个将被调用
+         * 开始运行场景时调用此方法，可以在派生类中覆盖
+         *
+         * 这个方法会在场景开始运行时被调用。您可以在这个方法中执行场景开始时需要进行的操作。
+         * 比如，您可以开始播放一段背景音乐、启动UI等等。
          */
         onStart(): void;
         /**
-         * 在场景子类中重写这个，并在这里做任何必要的卸载。
+         * 卸载场景时调用此方法，可以在派生类中覆盖
-         * 当Core把这个场景从活动槽中移除时，这个被调用。
+         *
+         * 这个方法会在场景被销毁时被调用。您可以在这个方法中销毁实体和组件、释放资源等等。
+         * 您也可以在这个方法中执行一些必要的清理工作，以确保场景被完全卸载。
          */
         unload(): void;
+        /**
+         * 开始场景，初始化物理系统、启动实体处理器等
+         *
+         * 这个方法会启动场景。它将重置物理系统、启动实体处理器等，并调用onStart方法。
+         */
         begin(): void;
+        /**
+         * 结束场景，清除实体、场景组件、物理系统等
+         *
+         * 这个方法会结束场景。它将移除所有实体并调用它们的onRemovedFromScene方法，清除物理系统，结束实体处理器等，并调用unload方法。
+         */
         end(): void;
+        /**
+         * 更新场景，更新实体组件、实体处理器等
+         */
         update(): void;
         /**
          * 向组件列表添加并返回SceneComponent
@@ -2678,49 +2727,51 @@ declare module es {
 }
 declare module es {
     /**
-     * 帮助处理位掩码的实用程序类
+     * 一个用于操作二进制标志（也称为位字段）
-     * 除了isFlagSet之外，所有方法都期望flag参数是一个非移位的标志
-     * 允许您使用普通的(0、1、2、3等)来设置/取消您的标记
      */
     class Flags {
         /**
-         * 检查位标志是否已在数值中设置
+         * 检查指定二进制数字中是否已设置了指定标志位
-         * 检查期望标志是否已经移位
+         * @param self 二进制数字
-         * @param self
+         * @param flag 标志位，应该为2的幂
-         * @param flag
+         * @returns 如果设置了指定的标志位，则返回true，否则返回false
          */
         static isFlagSet(self: number, flag: number): boolean;
         /**
-         * 检查位标志是否在数值中设置
+         * 检查指定二进制数字中是否已设置未移位的指定标志位
-         * @param self
+         * @param self 二进制数字
-         * @param flag
+         * @param flag 标志位，不应移位（应为2的幂）
+         * @returns 如果设置了指定的标志位，则返回true，否则返回false
          */
         static isUnshiftedFlagSet(self: number, flag: number): boolean;
         /**
-         *  设置数值标志位，移除所有已经设置的标志
+         * 将指定的标志位设置为二进制数字的唯一标志
-         * @param self
+         * @param self 二进制数字
-         * @param flag
+         * @param flag 标志位，应该为2的幂
          */
         static setFlagExclusive(self: Ref<number>, flag: number): void;
         /**
-         * 设置标志位
+         * 将指定的标志位设置为二进制数字
-         * @param self
+         * @param self 二进制数字的引用
-         * @param flag
+         * @param flag 标志位，应该为2的幂
          */
         static setFlag(self: Ref<number>, flag: number): void;
         /**
-         * 取消标志位
+         * 将指定的标志位从二进制数字中取消设置
-         * @param self
+         * @param self 二进制数字的引用
-         * @param flag
+         * @param flag 标志位，应该为2的幂
          */
         static unsetFlag(self: Ref<number>, flag: number): void;
         /**
-         * 反转数值集合位
+         * 反转二进制数字中的所有位（将1变为0，将0变为1）
-         * @param self
+         * @param self 二进制数字的引用
          */
         static invertFlags(self: Ref<number>): void;
         /**
-         * 打印 number 的二进制表示。 方便调试 number 标志
+         * 返回二进制数字的字符串表示形式（以二进制形式）
+         * @param self 二进制数字
+         * @param leftPadWidth 返回的字符串的最小宽度（在左侧填充0）
+         * @returns 二进制数字的字符串表示形式
          */
         static binaryStringRepresentation(self: number, leftPadWidth?: number): string;
     }
@@ -3589,6 +3640,13 @@ declare module es {
         static circleToLine(circleCenter: Vector2, radius: number, lineFrom: Vector2, lineTo: Vector2): boolean;
         static circleToPoint(circleCenter: Vector2, radius: number, point: Vector2): boolean;
         static rectToCircle(rect: Rectangle, cPosition: Vector2, cRadius: number): boolean;
+        /**
+         * 检查矩形和线段之间是否相交
+         * @param rect - 要检查的矩形
+         * @param lineFrom - 线段起点
+         * @param lineTo - 线段终点
+         * @returns 如果相交返回 true，否则返回 false
+         */
         static rectToLine(rect: Rectangle, lineFrom: Vector2, lineTo: Vector2): boolean;
         static rectToPoint(rX: number, rY: number, rW: number, rH: number, point: Vector2): boolean;
         /**
@@ -3804,13 +3862,13 @@ declare module es {
         _tempHashSet: Set<Collider>;
         constructor(cellSize?: number);
         /**
-         * 将对象添加到SpatialHash
+         * 注册一个碰撞器
-         * @param collider
+         * @param collider 碰撞器
          */
         register(collider: Collider): void;
         /**
-         * 从SpatialHash中删除对象
+         * 从空间哈希中移除一个碰撞器
-         * @param collider
+         * @param collider 碰撞器
          */
         remove(collider: Collider): void;
         /**
@@ -3820,64 +3878,90 @@ declare module es {
         removeWithBruteForce(obj: Collider): void;
         clear(): void;
         /**
-         * 返回边框与单元格相交的所有对象
+         * 执行基于 AABB 的广域相交检测并返回碰撞器列表
-         * @param bounds
+         * @param bounds 边界矩形
-         * @param excludeCollider
+         * @param excludeCollider 排除的碰撞器
-         * @param layerMask
+         * @param layerMask 碰撞层掩码
+         * @returns 碰撞器列表
          */
         aabbBroadphase(bounds: Rectangle, excludeCollider: Collider, layerMask: number): Collider[];
         /**
-         * 通过空间散列投掷一条线，并将该线碰到的任何碰撞器填入碰撞数组
+         * 执行基于线段的射线检测并返回所有命中的碰撞器
-         * https://github.com/francisengelmann/fast_voxel_traversal/blob/master/main.cpp
+         * @param start 射线起点
-         * http://www.cse.yorku.ca/~amana/research/grid.pdf
+         * @param end 射线终点
-         * @param start
+         * @param hits 射线命中结果
-         * @param end
+         * @param layerMask 碰撞层掩码
-         * @param hits
+         * @param ignoredColliders 忽略的碰撞器
-         * @param layerMask
+         * @returns 命中的碰撞器数量
          */
         linecast(start: Vector2, end: Vector2, hits: RaycastHit[], layerMask: number, ignoredColliders: Set<Collider>): number;
         /**
-         * 获取所有在指定矩形范围内的碰撞器
+         * 执行矩形重叠检测并返回所有命中的碰撞器
-         * @param rect
+         * @param rect 矩形
-         * @param results
+         * @param results 碰撞器命中结果
-         * @param layerMask
+         * @param layerMask 碰撞层掩码
+         * @returns 命中的碰撞器数量
          */
         overlapRectangle(rect: Rectangle, results: Collider[], layerMask: number): number;
         /**
-         * 获取所有落在指定圆圈内的碰撞器
+         * 执行圆形重叠检测并返回所有命中的碰撞器
-         * @param circleCenter
+         * @param circleCenter 圆心坐标
-         * @param radius
+         * @param radius 圆形半径
-         * @param results
+         * @param results 碰撞器命中结果
-         * @param layerMask
+         * @param layerMask 碰撞层掩码
+         * @returns 命中的碰撞器数量
          */
-        overlapCircle(circleCenter: Vector2, radius: number, results: Collider[], layerMask: any): number;
+        overlapCircle(circleCenter: Vector2, radius: number, results: Collider[], layerMask: number): number;
         /**
-         * 获取单元格的x,y值作为世界空间的x,y值
+         * 将给定的 x 和 y 坐标转换为单元格坐标
-         * @param x
+         * @param x X 坐标
-         * @param y
+         * @param y Y 坐标
+         * @returns 转换后的单元格坐标
          */
         cellCoords(x: number, y: number): Vector2;
         /**
-         * 获取世界空间x,y值的单元格。
+         * 返回一个包含特定位置处的所有碰撞器的数组
-         * 如果单元格为空且createCellIfEmpty为true，则会创建一个新的单元格
+         * 如果此位置上没有单元格并且createCellIfEmpty参数为true，则会创建一个新的单元格
-         * @param x
+         * @param x 单元格 x 坐标
-         * @param y
+         * @param y 单元格 y 坐标
-         * @param createCellIfEmpty
+         * @param createCellIfEmpty 如果该位置上没有单元格是否创建一个新单元格，默认为false
+         * @returns 该位置上的所有碰撞器
          */
         cellAtPosition(x: number, y: number, createCellIfEmpty?: boolean): Collider[];
     }
+    /**
+     * 数字字典
+     */
     class NumberDictionary<T> {
         _store: Map<string, T[]>;
+        /**
+         * 将指定的列表添加到以给定 x 和 y 为键的字典条目中
+         * @param x 字典的 x 坐标
+         * @param y 字典的 y 坐标
+         * @param list 要添加到字典的列表
+         */
         add(x: number, y: number, list: T[]): void;
         /**
-         * 使用蛮力方法从字典存储列表中移除碰撞器
+         * 从字典中删除给定的对象
-         * @param obj
+         * @param obj 要删除的对象
          */
         remove(obj: T): void;
+        /**
+         * 尝试从字典中检索指定键的值
+         * @param x 字典的 x 坐标
+         * @param y 字典的 y 坐标
+         * @returns 指定键的值，如果不存在则返回 null
+         */
         tryGetValue(x: number, y: number): T[];
+        /**
+         * 根据给定的 x 和 y 坐标返回一个唯一的字符串键
+         * @param x 字典的 x 坐标
+         * @param y 字典的 y 坐标
+         * @returns 唯一的字符串键
+         */
         getKey(x: number, y: number): string;
         /**
-         * 清除字典数据
+         * 清空字典
          */
         clear(): void;
     }
@@ -3893,10 +3977,11 @@ declare module es {
         private _ignoredColliders;
         start(ray: Ray2D, hits: RaycastHit[], layerMask: number, ignoredColliders: Set<Collider>): void;
         /**
-         * 如果hits数组被填充，返回true。单元格不能为空!
+         * 对射线检测到的碰撞器进行进一步的处理，将结果存储在传递的碰撞数组中。
-         * @param cellX
+         * @param cellX 当前单元格的x坐标
-         * @param cellY
+         * @param cellY 当前单元格的y坐标
-         * @param cell
+         * @param cell 该单元格中的碰撞器列表
+         * @returns 如果当前单元格有任何碰撞器与射线相交，则返回true
          */
         checkRayIntersection(cellX: number, cellY: number, cell: Collider[]): boolean;
         reset(): void;
@@ -4539,33 +4624,33 @@ declare module es {
     }
 }
 declare module es {
+    /**
+     * 全局管理器的基类。所有全局管理器都应该从此类继承。
+     */
     class GlobalManager {
+        /**
+         * 表示管理器是否启用
+         */
         _enabled: boolean;
         /**
-         * 如果true则启用了GlobalManager。
+         * 获取或设置管理器是否启用
-         * 状态的改变会导致调用OnEnabled/OnDisable
-         */
-        /**
-        * 如果true则启用了GlobalManager。
-        * 状态的改变会导致调用OnEnabled/OnDisable
-        * @param value
          */
         enabled: boolean;
         /**
-         * 启用/禁用这个GlobalManager
+         * 设置管理器是否启用
-         * @param isEnabled
+         * @param isEnabled 如果为true，则启用管理器；否则禁用管理器
          */
         setEnabled(isEnabled: boolean): void;
         /**
-         * 此GlobalManager启用时调用
+         * 在启用管理器时调用的回调方法
          */
         onEnabled(): void;
         /**
-         * 此GlobalManager禁用时调用
+         * 在禁用管理器时调用的回调方法
          */
         onDisabled(): void;
         /**
-         * 在frame .update之前调用每一帧
+         * 更新管理器状态的方法
          */
         update(): void;
     }

source/src/Core.ts

@@ -93,12 +93,16 @@ module es {
         }
 
         /**
-         * 默认实现创建核心
+         * `Core`类的静态方法，用于创建`Core`的实例。
+         * @param debug {boolean} 是否为调试模式，默认为`true`
+         * @returns {Core} `Core`的实例
          */
         public static create(debug: boolean = true): Core {
+            // 如果实例还未被创建，则创建一个新的实例并保存在`_instance`静态属性中
             if (this._instance == null) {
                 this._instance = new es.Core(debug);
             }
+            // 返回`_instance`静态属性中保存的实例
             return this._instance;
         }
 
@@ -197,35 +201,47 @@ module es {
 
         }
 
-        protected update(currentTime: number = -1) {
+        /**
+         * `Core` 类的受保护的 `update` 方法，用于更新游戏状态。
+         * @param currentTime 当前时间戳，单位为毫秒，默认值为-1。
+         */
+        protected update(currentTime: number = -1): void {
+            // 如果引擎处于暂停状态，则直接返回，不做任何操作
             if (Core.paused) {
                 return;
             }
 
-            Time.update(currentTime, currentTime != -1);
+            // 更新时间戳信息
+            Time.update(currentTime, currentTime !== -1);
+
+            // 更新全局管理器和当前场景
             if (this._scene != null) {
-                for (let i = this._globalManagers.length - 1; i >= 0; i--) {
+                // 依次更新所有启用的全局管理器
-                    if (this._globalManagers[i].enabled)
+                for (const globalManager of this._globalManagers) {
-                        this._globalManagers[i].update();
+                    if (globalManager.enabled) {
+                        globalManager.update();
+                    }
                 }
 
-                if (this._sceneTransition == null ||
+                // 如果当前没有场景切换正在进行，或者正在进行的场景切换不需要加载新场景
-                    (this._sceneTransition != null &&
+                if (this._sceneTransition == null || !this._sceneTransition._loadsNewScene) {
-                        (!this._sceneTransition._loadsNewScene || this._sceneTransition._isNewSceneLoaded))) {
                     this._scene.update();
                 }
+            }
 
+            // 处理场景切换
             if (this._nextScene != null) {
+                // 结束当前场景
                 this._scene.end();
 
+                // 加载并初始化新场景
                 this._scene = this._nextScene;
                 this._nextScene = null;
                 this.onSceneChanged();
-
                 this._scene.begin();
             }
-            }
 
+            // 绘制调试信息
             this.startDebugDraw();
             this.draw();
         }

source/src/ECS/Scene.ts

@@ -21,39 +21,60 @@ module es {
         }
 
         /**
-         * 在场景子类中重写这个，然后在这里进行加载。
+         * 初始化场景，可以在派生类中覆盖
-         * 在场景设置好之后，但在调用begin之前，从contructor中调用这个函数
+         *
+         * 这个方法会在场景创建时被调用。您可以在这个方法中添加实体和组件，
+         * 或者执行一些必要的准备工作，以便场景能够开始运行。
          */
         public initialize() {
         }
 
         /**
-         * 当Core将这个场景设置为活动场景时，这个将被调用
+         * 开始运行场景时调用此方法，可以在派生类中覆盖
+         *
+         * 这个方法会在场景开始运行时被调用。您可以在这个方法中执行场景开始时需要进行的操作。
+         * 比如，您可以开始播放一段背景音乐、启动UI等等。
          */
         public onStart() {
         }
 
         /**
-         * 在场景子类中重写这个，并在这里做任何必要的卸载。
+         * 卸载场景时调用此方法，可以在派生类中覆盖
-         * 当Core把这个场景从活动槽中移除时，这个被调用。
+         *
+         * 这个方法会在场景被销毁时被调用。您可以在这个方法中销毁实体和组件、释放资源等等。
+         * 您也可以在这个方法中执行一些必要的清理工作，以确保场景被完全卸载。
          */
         public unload() {
         }
 
+        /**
+         * 开始场景，初始化物理系统、启动实体处理器等
+         *
+         * 这个方法会启动场景。它将重置物理系统、启动实体处理器等，并调用onStart方法。
+         */
         public begin() {
+            // 重置物理系统
             Physics.reset();
 
+            // 启动实体处理器
             if (this.entityProcessors != null)
                 this.entityProcessors.begin();
 
+            // 标记场景已开始运行并调用onStart方法
             this._didSceneBegin = true;
             this.onStart();
-
         }
 
+        /**
+         * 结束场景，清除实体、场景组件、物理系统等
+         *
+         * 这个方法会结束场景。它将移除所有实体并调用它们的onRemovedFromScene方法，清除物理系统，结束实体处理器等，并调用unload方法。
+         */
         public end() {
+            // 标记场景已结束运行
             this._didSceneBegin = false;
 
+            // 移除所有实体并调用它们的onRemovedFromScene方法
             this.entities.removeAllEntities();
 
             for (let i = 0; i < this._sceneComponents.length; i++) {
@@ -61,30 +82,38 @@ module es {
             }
             this._sceneComponents.length = 0;
 
+            // 清除物理系统
             Physics.clear();
 
+            // 结束实体处理器
             if (this.entityProcessors)
                 this.entityProcessors.end();
 
+            // 调用卸载方法
             this.unload();
         }
 
+        /**
+         * 更新场景，更新实体组件、实体处理器等
+         */
         public update() {
-            // 更新我们的列表，以防它们有任何变化
+            // 更新实体列表
             this.entities.updateLists();
 
+            // 更新场景组件
             for (let i = this._sceneComponents.length - 1; i >= 0; i--) {
                 if (this._sceneComponents[i].enabled)
                     this._sceneComponents[i].update();
             }
 
-            // 更新我们的实体解析器
+            // 更新实体处理器
             if (this.entityProcessors != null)
                 this.entityProcessors.update();
 
-            // 更新我们的实体组
+            // 更新实体组
             this.entities.update();
 
+            // 更新实体处理器的后处理方法
             if (this.entityProcessors != null)
                 this.entityProcessors.lateUpdate();
         }