更改示例及新增注释

This commit is contained in:
yhh
2023-03-14 14:03:41 +08:00
parent 78e0b09c7a
commit 3363fca160
7 changed files with 695 additions and 388 deletions
+3
View File
@@ -0,0 +1,3 @@
{
"toolchains": []
}
+40 -24
View File
@@ -3,15 +3,19 @@
## 初始化框架
```typescript
// 参数为false则开启debug模式
es.Core.create(false);
// 创建调试模式下的`Core`实例
const core = es.Core.create();
// 创建非调试模式下的`Core`实例
const core = es.Core.create(false);
```
## 分发帧事件
```typescript
// 放置于引擎每帧更新处
// dt为可选参数,传入引擎的deltaTime代替框架内的es.Time.deltaTime
// dt 是一个可选参数,如果传入了 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 {
/**
* 可重写方法,从contructor中调用这个函数
*/
initialize() {
console.log('initialize');
/** 示例场景 */
export class MainScene extends Scene {
constructor() {
super();
}
/**
* 可重写方法。当Core将这个场景设置为活动场景时调用
*/
onStart() {
console.log('onStart');
* 初始化场景,添加实体和组件
*
* 这个方法会在场景被创建时被调用。我们在这个方法中创建了一个实体,
* 并向它添加了一个SpriteRender组件和一个TransformMove组件。
*/
public initialize() {
// 创建一个实体
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() {
console.log('unload');
* 场景开始运行时执行的操作
*
* 这个方法会在场景开始运行时被调用。我们在这个方法中输出一条消息表示场景已经开始运行。
*/
public onStart() {
console.log("MainScene has started!");
}
/**
* 可重写方法。
*/
update() {
// 如果重写update方法 一定要调用该方法
// 不调用将导致实体无法加入/组件无法更新
super.update();
* 场景被销毁时执行的操作
*
* 这个方法会在场景被销毁时被调用。我们在这个方法中输出一条消息表示场景已经被卸载。
*/
public unload() {
console.log("MainScene has been unloaded!");
}
}
```
+169 -84
View File
@@ -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 flag
* 检查指定二进制数字中是否已设置了指定标志位
* @param self 二进制数字
* @param flag 标志位,应该为2的幂
* @returns 如果设置了指定的标志位,则返回true,否则返回false
*/
static isFlagSet(self: number, flag: number): boolean;
/**
* 检查位标志是否在数值中设置
* @param self
* @param flag
* 检查指定二进制数字中是否已设置未移位的指定标志位
* @param self 二进制数字
* @param flag 标志位,不应移位(应为2的幂)
* @returns 如果设置了指定的标志位,则返回true,否则返回false
*/
static isUnshiftedFlagSet(self: number, flag: number): boolean;
/**
* 设置数值标志位,移除所有已经设置的标志
* @param self
* @param flag
* 将指定的标志位设置为二进制数字的唯一标志
* @param self 二进制数字
* @param flag 标志位,应该为2的幂
*/
static setFlagExclusive(self: Ref<number>, flag: number): void;
/**
* 设置标志位
* @param self
* @param flag
* 将指定的标志位设置为二进制数字
* @param self 二进制数字的引用
* @param flag 标志位,应该为2的幂
*/
static setFlag(self: Ref<number>, flag: number): void;
/**
* 取消标志位
* @param self
* @param flag
* 将指定的标志位从二进制数字中取消设置
* @param self 二进制数字的引用
* @param flag 标志位,应该为2的幂
*/
static unsetFlag(self: Ref<number>, flag: number): void;
/**
* 反转数值集合位
* @param self
* 反转二进制数字中的所有位(将1变为0,将0变为1)
* @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;
/**
* 返回边框与单元格相交的所有对象
* @param bounds
* @param excludeCollider
* @param layerMask
* 执行基于 AABB 的广域相交检测并返回碰撞器列表
* @param bounds 边界矩形
* @param excludeCollider 排除的碰撞器
* @param layerMask 碰撞层掩码
* @returns 碰撞器列表
*/
aabbBroadphase(bounds: Rectangle, excludeCollider: Collider, layerMask: number): Collider[];
/**
* 通过空间散列投掷一条线,并将该线碰到的任何碰撞器填入碰撞数组
* https://github.com/francisengelmann/fast_voxel_traversal/blob/master/main.cpp
* http://www.cse.yorku.ca/~amana/research/grid.pdf
* @param start
* @param end
* @param hits
* @param layerMask
* 执行基于线段的射线检测并返回所有命中的碰撞器
* @param start 射线起点
* @param end 射线终点
* @param hits 射线命中结果
* @param layerMask 碰撞层掩码
* @param ignoredColliders 忽略的碰撞器
* @returns 命中的碰撞器数量
*/
linecast(start: Vector2, end: Vector2, hits: RaycastHit[], layerMask: number, ignoredColliders: Set<Collider>): number;
/**
* 获取所有在指定矩形范围内的碰撞器
* @param rect
* @param results
* @param layerMask
* 执行矩形重叠检测并返回所有命中的碰撞器
* @param rect 矩形
* @param results 碰撞器命中结果
* @param layerMask 碰撞层掩码
* @returns 命中的碰撞器数量
*/
overlapRectangle(rect: Rectangle, results: Collider[], layerMask: number): number;
/**
* 获取所有落在指定圆圈内的碰撞器
* @param circleCenter
* @param radius
* @param results
* @param layerMask
* 执行圆形重叠检测并返回所有命中的碰撞器
* @param circleCenter 圆心坐标
* @param radius 圆形半径
* @param results 碰撞器命中结果
* @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值
* @param x
* @param y
* 将给定的 x 和 y 坐标转换为单元格坐标
* @param x X 坐标
* @param y Y 坐标
* @returns 转换后的单元格坐标
*/
cellCoords(x: number, y: number): Vector2;
/**
* 获取世界空间x,y值的单元格。
* 如果单元格为空且createCellIfEmpty为true,则会创建一个新的单元格
* @param x
* @param y
* @param createCellIfEmpty
* 返回一个包含特定位置处的所有碰撞器的数组
* 如果此位置上没有单元格且createCellIfEmpty参数为true,则会创建一个新的单元格
* @param x 单元格 x 坐标
* @param y 单元格 y 坐标
* @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 cellY
* @param cell
* 对射线检测到的碰撞器进行进一步的处理,将结果存储在传递的碰撞数组中。
* @param cellX 当前单元格的x坐标
* @param cellY 当前单元格的y坐标
* @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;
}
+403 -245
View File
File diff suppressed because it is too large Load Diff
+1 -1
View File
File diff suppressed because one or more lines are too long
+35 -19
View File
@@ -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)
this._globalManagers[i].update();
// 依次更新所有启用的全局管理器
for (const globalManager of this._globalManagers) {
if (globalManager.enabled) {
globalManager.update();
}
}
if (this._sceneTransition == null ||
(this._sceneTransition != null &&
(!this._sceneTransition._loadsNewScene || this._sceneTransition._isNewSceneLoaded))) {
// 如果当前没有场景切换正在进行,或者正在进行的场景切换不需要加载新场景
if (this._sceneTransition == null || !this._sceneTransition._loadsNewScene) {
this._scene.update();
}
if (this._nextScene != null) {
this._scene.end();
this._scene = this._nextScene;
this._nextScene = null;
this.onSceneChanged();
this._scene.begin();
}
}
// 处理场景切换
if (this._nextScene != null) {
// 结束当前场景
this._scene.end();
// 加载并初始化新场景
this._scene = this._nextScene;
this._nextScene = null;
this.onSceneChanged();
this._scene.begin();
}
// 绘制调试信息
this.startDebugDraw();
this.draw();
}
+44 -15
View File
@@ -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();
}
@@ -193,8 +222,8 @@ module es {
/**
*
* @param tag
* @returns
* @param tag
* @returns
*/
public findEntityWithTag(tag: number): Entity {
return this.entities.entityWithTag(tag);
@@ -218,8 +247,8 @@ module es {
/**
*
* @param type
* @returns
* @param type
* @returns
*/
public findEntitiesOfComponent(...types): Entity[] {
return this.entities.findEntitiesOfComponent(...types);
@@ -232,7 +261,7 @@ module es {
public addEntityProcessor(processor: EntitySystem) {
processor.scene = this;
this.entityProcessors.add(processor);
processor.setUpdateOrder(this.entityProcessors.count - 1);
this.entityProcessors.clearDirty();
return processor;