diff --git a/EngineErrorMap.md b/EngineErrorMap.md
index 126c1c66c00..c31339ff6e8 100644
--- a/EngineErrorMap.md
+++ b/EngineErrorMap.md
@@ -38,7 +38,7 @@ loadScene: Unknown name type to load: '%s'
### 1208
-loadScene: Failed to load scene '%s' because '%s' is already loading
+loadScene: Failed to load scene '%s' because '%s' is already being loaded.
### 1209
diff --git a/cocos/core/components/component-event-handler.ts b/cocos/core/components/component-event-handler.ts
index 7f96af63697..9e9092606c6 100644
--- a/cocos/core/components/component-event-handler.ts
+++ b/cocos/core/components/component-event-handler.ts
@@ -33,11 +33,25 @@ import { Node } from '../scene-graph';
import { legacyCC } from '../global-exports';
/**
+ * @en
+ * Component will register a event to target component's handler. And it will trigger the handler when a certain event occurs.
+ *
* @zh
* “EventHandler” 类用来设置场景中的事件回调,该类允许用户设置回调目标节点,目标组件名,组件方法名,并可通过 emit 方法调用目标函数。
*
* @example
* ```ts
+ * // Let's say we have a MainMenu component on newTarget
+ * // file: MainMenu.ts
+ * @ccclass('MainMenu')
+ * export class MainMenu extends Component {
+ * // sender: the node MainMenu.ts belongs to
+ * // eventType: CustomEventData
+ * onClick (sender, eventType) {
+ * cc.log('click');
+ * }
+ * }
+ *
* import { Component } from 'cc';
* const eventHandler = new Component.EventHandler();
* eventHandler.target = newTarget;
@@ -59,6 +73,8 @@ export class EventHandler {
}
/**
+ * @en
+ * For component event emit
* @zh
* 组件事件派发。
*
@@ -76,14 +92,18 @@ export class EventHandler {
}
}
/**
+ * @en
+ * The node that contains target callback, such as the node example script belongs to
* @zh
- * 目标节点。
+ * 事件响应函数所在节点 ,比如例子中脚本归属的节点本身
*/
@type(legacyCC.Node)
public target: Node | null = null;
/**
+ * @en
+ * The name of the component(script) that contains target callback, such as the name 'MainMenu' of script in example
* @zh
- * 目标组件名。
+ * 事件响应函数所在组件名(脚本名), 比如例子中的脚本名 'MainMenu'
*/
// only for deserializing old project component field
@property
@@ -93,20 +113,26 @@ export class EventHandler {
public _componentId = '';
/**
+ * @en
+ * Event handler, such as function's name 'onClick' in example
* @zh
- * 响应事件函数名。
+ * 响应事件函数名,比如例子中的 'onClick'
*/
@property
public handler = '';
/**
+ * @en
+ * Custom Event Data, such as 'eventType' in example
* @zh
- * 自定义事件数据。
+ * 自定义事件数据,比如例子中的 eventType
*/
@property
public customEventData = '';
/**
+ * @en
+ * Emit event with params
* @zh
* 触发目标组件上的指定 handler 函数,该参数是回调函数的参数值(可不填)。
*
diff --git a/cocos/core/components/component.ts b/cocos/core/components/component.ts
index 2663a5ae9b6..e0c8f189c8e 100644
--- a/cocos/core/components/component.ts
+++ b/cocos/core/components/component.ts
@@ -418,9 +418,10 @@ class Component extends CCObject {
*/
public schedule (callback, interval: number = 0, repeat: number = legacyCC.macro.REPEAT_FOREVER, delay: number = 0) {
assertID(callback, 1619);
- assertID(interval >= 0, 1620);
interval = interval || 0;
+ assertID(interval >= 0, 1620);
+
repeat = isNaN(repeat) ? legacyCC.macro.REPEAT_FOREVER : repeat;
delay = delay || 0;
diff --git a/cocos/core/director.ts b/cocos/core/director.ts
index 8fdc4f87e2f..215641c2d76 100644
--- a/cocos/core/director.ts
+++ b/cocos/core/director.ts
@@ -47,7 +47,7 @@ import { Scheduler } from './scheduler';
import { js } from './utils';
import { DEBUG, EDITOR, BUILD } from 'internal:constants';
import { legacyCC } from './global-exports';
-import { errorID, error, logID, assertID } from './platform/debug';
+import { errorID, error, logID, assertID, warnID } from './platform/debug';
// ----------------------------------------------------------------------------------------------------------------------
@@ -270,6 +270,7 @@ export class Director extends EventTarget {
private _totalFrames: number;
private _lastUpdate: number;
private _deltaTime: number;
+ private _startTime: number;
private _scheduler: Scheduler;
private _systems: System[];
@@ -293,6 +294,7 @@ export class Director extends EventTarget {
this._totalFrames = 0;
this._lastUpdate = 0;
this._deltaTime = 0.0;
+ this._startTime = 0.0;
// Scheduler for user registration update
this._scheduler = new Scheduler();
@@ -309,8 +311,8 @@ export class Director extends EventTarget {
/**
* calculates delta time since last time it was called
*/
- public calculateDeltaTime () {
- const now = performance.now();
+ public calculateDeltaTime (now) {
+ if (!now) now = performance.now();
this._deltaTime = now > this._lastUpdate ? (now - this._lastUpdate) / 1000 : 0;
if (DEBUG && (this._deltaTime > 1)) {
@@ -640,7 +642,7 @@ export class Director extends EventTarget {
*/
public loadScene (sceneName: string, onLaunched?: Director.OnSceneLaunched, onUnloaded?: Director.OnUnload) {
if (this._loadingScene) {
- errorID(1208, sceneName, this._loadingScene);
+ warnID(1208, sceneName, this._loadingScene);
return false;
}
const info = this._getSceneUuid(sceneName);
@@ -904,6 +906,14 @@ export class Director extends EventTarget {
return this._deltaTime;
}
+ /**
+ * @en Returns the total passed time since game start, unit: ms
+ * @zh 获取从游戏开始到现在总共经过的时间,单位为 ms
+ */
+ public getTotalTime () {
+ return performance.now() - this._startTime;
+ }
+
/**
* @en Returns the current time.
* @zh 获取当前帧的时间。
@@ -1013,7 +1023,7 @@ export class Director extends EventTarget {
}
else if (!this._invalid) {
// calculate "global" dt
- this.calculateDeltaTime();
+ this.calculateDeltaTime(time);
const dt = this._deltaTime;
// Update
@@ -1053,6 +1063,7 @@ export class Director extends EventTarget {
private _initOnRendererInitialized () {
this._totalFrames = 0;
this._lastUpdate = performance.now();
+ this._startTime = this._lastUpdate;
this._paused = false;
this._purgeDirectorInNextLoop = false;
diff --git a/cocos/core/game.ts b/cocos/core/game.ts
index a9c1d6b6d9d..92bd7edef15 100644
--- a/cocos/core/game.ts
+++ b/cocos/core/game.ts
@@ -229,8 +229,7 @@ export interface IGameConfig {
/**
* @en An object to boot the game.
* @zh 包含游戏主体信息并负责驱动游戏的游戏对象。
- * @class game
- * @static
+ * @class Game
*/
export class Game extends EventTarget {
/**
@@ -987,10 +986,11 @@ export class Game extends EventTarget {
legacyCC.game.emit(Game.EVENT_HIDE);
}
}
- function onShown () {
+ // In order to adapt the most of platforms the onshow API.
+ function onShown (arg0?, arg1?, arg2?, arg3?, arg4?) {
if (hidden) {
hidden = false;
- legacyCC.game.emit(Game.EVENT_SHOW);
+ legacyCC.game.emit(Game.EVENT_SHOW, arg0, arg1, arg2, arg3, arg4);
}
}
@@ -1067,4 +1067,11 @@ export class Game extends EventTarget {
}
legacyCC.Game = Game;
-export const game = legacyCC.game = new Game();
\ No newline at end of file
+
+/**
+ * @en
+ * This is a Game instance.
+ * @zh
+ * 这是一个 Game 类的实例,包含游戏主体信息并负责驱动游戏的游戏对象。
+ */
+export const game = legacyCC.game = new Game();
diff --git a/cocos/core/platform/event-manager/events.ts b/cocos/core/platform/event-manager/events.ts
index f3fd76308b9..b876842574b 100644
--- a/cocos/core/platform/event-manager/events.ts
+++ b/cocos/core/platform/event-manager/events.ts
@@ -535,7 +535,7 @@ export class EventTouch extends Event {
/**
* @en Returns the start touch location.
- * @zh 获获取触点落下时的位置对象,对象包含 x 和 y 属性。
+ * @zh 获取触点落下时的位置对象,对象包含 x 和 y 属性。
* @param out - Pass the out object to avoid object creation, very good practice
*/
public getStartLocation (out?: Vec2) {
@@ -544,7 +544,7 @@ export class EventTouch extends Event {
/**
* @en Returns the start touch location in UI coordinates.
- * @zh 获获取触点落下时的 UI 世界下位置对象,对象包含 x 和 y 属性。
+ * @zh 获取触点落下时的 UI 世界下位置对象,对象包含 x 和 y 属性。
* @param out - Pass the out object to avoid object creation, very good practice
*/
public getUIStartLocation(out?: Vec2) {
diff --git a/cocos/core/platform/event-manager/touch.ts b/cocos/core/platform/event-manager/touch.ts
index 756d77db8d0..101453c3319 100644
--- a/cocos/core/platform/event-manager/touch.ts
+++ b/cocos/core/platform/event-manager/touch.ts
@@ -151,7 +151,7 @@ export class Touch {
/**
* @en Returns the start touch location.
- * @zh 获获取触点落下时的位置对象,对象包含 x 和 y 属性。
+ * @zh 获取触点落下时的位置对象,对象包含 x 和 y 属性。
* @param out - Pass the out object to avoid object creation, very good practice
*/
public getStartLocation (out?: Vec2) {
@@ -165,7 +165,7 @@ export class Touch {
/**
* @en Returns the start touch location in UI coordinates.
- * @zh 获获取触点落下时在 UI 坐标系中的位置对象,对象包含 x 和 y 属性。
+ * @zh 获取触点落下时在 UI 坐标系中的位置对象,对象包含 x 和 y 属性。
* @param out - Pass the out object to avoid object creation, very good practice
*/
public getUIStartLocation (out?: Vec2) {
diff --git a/cocos/core/scene-graph/node.ts b/cocos/core/scene-graph/node.ts
index cbdbea49b33..eac4d0cc9bd 100644
--- a/cocos/core/scene-graph/node.ts
+++ b/cocos/core/scene-graph/node.ts
@@ -992,8 +992,13 @@ export class Node extends BaseNode {
}
/**
- * @en Pause all system events which is dispatched by [[SystemEvent]]
- * @zh 暂停所有 [[SystemEvent]] 派发的系统事件
+ * @en
+ * Pause all system events which is dispatched by [[SystemEvent]].
+ * If recursive is set to true, then this API will pause the node system events for the node and all nodes in its sub node tree.
+ * @zh
+ * 暂停所有 [[SystemEvent]] 派发的系统事件。
+ * 如果传递 recursive 为 true,那么这个 API 将暂停本节点和它的子树上所有节点的节点系统事件。
+ *
* @param recursive Whether pause system events recursively for the child node tree
*/
public pauseSystemEvents (recursive: boolean): void {
@@ -1002,8 +1007,14 @@ export class Node extends BaseNode {
}
/**
- * @en Resume all paused system events which is dispatched by [[SystemEvent]]
- * @zh 恢复所有 [[SystemEvent]] 派发的系统事件
+ * @en
+ * Resume all paused system events which is dispatched by [[SystemEvent]].
+ * If recursive is set to true, then this API will resume the node system events for the node and all nodes in its sub node tree.
+ *
+ * @zh
+ * 恢复所有 [[SystemEvent]] 派发的系统事件。
+ * 如果传递 recursive 为 true,那么这个 API 将恢复本节点和它的子树上所有节点的节点系统事件。
+ *
* @param recursive Whether resume system events recursively for the child node tree
*/
public resumeSystemEvents (recursive: boolean): void {
diff --git a/cocos/core/scheduler.ts b/cocos/core/scheduler.ts
index f35d010a503..cf8f1039da9 100644
--- a/cocos/core/scheduler.ts
+++ b/cocos/core/scheduler.ts
@@ -683,10 +683,10 @@ export class Scheduler extends System {
/**
* @en
- * Unschedules a callback for a callback and a given target.
+ * Unschedules a callback for a callback and a given target.
* If you want to unschedule the "update", use `unscheduleUpdate()`
* @zh
- * 根据指定的回调函数和调用对象。
+ * 取消指定对象定时器。
* 如果需要取消 update 定时器,请使用 unscheduleUpdate()。
* @param {Function} callback The callback to be unscheduled
* @param {Object} target The target bound to the callback.
@@ -807,7 +807,7 @@ export class Scheduler extends System {
* You should NEVER call this method, unless you know what you are doing.
* @zh
* 取消所有对象的所有定时器,包括系统定时器。
- * 不用调用此函数,除非你确定你在做什么。
+ * 不要调用此函数,除非你确定你在做什么。
*/
public unscheduleAll (){
this.unscheduleAllWithMinPriority(legacyCC.Scheduler.PRIORITY_SYSTEM);
diff --git a/cocos/ui/components/button-component.ts b/cocos/ui/components/button-component.ts
index 1fd6e0a7a4f..f8936698f09 100644
--- a/cocos/ui/components/button-component.ts
+++ b/cocos/ui/components/button-component.ts
@@ -109,27 +109,33 @@ export enum EventType {
* User can get the current clicked node with 'event.target' from event object which is passed as parameter in the callback function of click event.
*
* @zh
- * 按钮组件。可以被按下,或者点击。
+ * 按钮组件。可以被按下,或者点击。
*
- * 按钮可以通过修改 Transition 来设置按钮状态过渡的方式:
- * - `Button.Transition.NONE` // 不做任何过渡
- * - `Button.Transition.COLOR` // 进行颜色之间过渡
- * - `Button.Transition.SPRITE` // 进行精灵之间过渡
- * - `Button.Transition.SCALE` // 进行缩放过渡
+ * 按钮可以通过修改 Transition 来设置按钮状态过渡的方式:
+ *
+ * - Button.Transition.NONE // 不做任何过渡
+ * - Button.Transition.COLOR // 进行颜色之间过渡
+ * - Button.Transition.SPRITE // 进行精灵之间过渡
+ * - Button.Transition.SCALE // 进行缩放过渡
*
* 按钮可以绑定事件(但是必须要在按钮的 Node 上才能绑定事件):
- * // 以下事件可以在全平台上都触发
- * - `Node.EventType.TOUCH_START` // 按下时事件
- * - `Node.EventType.TOUCH_Move` // 按住移动后事件
- * - `Node.EventType.TOUCH_END` // 按下后松开后事件
- * - `Node.EventType.TOUCH_CANCEL` // 按下取消事件
- * // 以下事件只在 PC 平台上触发
- * - `Node.EventType.MOUSE_DOWN` // 鼠标按下时事件
- * - `Node.EventType.MOUSE_MOVE` // 鼠标按住移动后事件
- * - `Node.EventType.MOUSE_ENTER` // 鼠标进入目标事件
- * - `Node.EventType.MOUSE_LEAVE` // 鼠标离开目标事件
- * - `Node.EventType.MOUSE_UP` // 鼠标松开事件
- * - `Node.EventType.MOUSE_WHEEL` // 鼠标滚轮事件
+ * 以下事件可以在全平台上都触发:
+ *
+ * - cc.Node.EventType.TOUCH_START // 按下时事件
+ * - cc.Node.EventType.TOUCH_Move // 按住移动后事件
+ * - cc.Node.EventType.TOUCH_END // 按下后松开后事件
+ * - cc.Node.EventType.TOUCH_CANCEL // 按下取消事件
+ *
+ * 以下事件只在 PC 平台上触发:
+ *
+ * - cc.Node.EventType.MOUSE_DOWN // 鼠标按下时事件
+ * - cc.Node.EventType.MOUSE_MOVE // 鼠标按住移动后事件
+ * - cc.Node.EventType.MOUSE_ENTER // 鼠标进入目标事件
+ * - cc.Node.EventType.MOUSE_LEAVE // 鼠标离开目标事件
+ * - cc.Node.EventType.MOUSE_UP // 鼠标松开事件
+ * - cc.Node.EventType.MOUSE_WHEEL // 鼠标滚轮事件
+ *
+ * 用户可以通过获取 __点击事件__ 回调函数的参数 event 的 target 属性获取当前点击对象。
*
* @example
* ```ts
diff --git a/cocos/ui/components/label-component.ts b/cocos/ui/components/label-component.ts
index 0a7d31d2a6a..9df157b75a1 100644
--- a/cocos/ui/components/label-component.ts
+++ b/cocos/ui/components/label-component.ts
@@ -119,7 +119,7 @@ export enum Overflow {
* @en In SHRINK mode, the font size will change dynamically to adapt the content size.
* This mode may takes up more CPU resources when the label is refreshed.
*
- * @zh SHRINK 模式,字体大小会动态变化,以适应内容大小。
+ * @zh SHRINK 模式,字体大小会动态变化,以适应内容大小。这个模式在文本刷新的时候可能会占用较多 CPU 资源。
*/
SHRINK = 2,
/**
diff --git a/cocos/ui/components/slider-component.ts b/cocos/ui/components/slider-component.ts
index 49193f59b9e..152e86aa9c8 100644
--- a/cocos/ui/components/slider-component.ts
+++ b/cocos/ui/components/slider-component.ts
@@ -157,7 +157,7 @@ export class SliderComponent extends Component {
* The slider slide events' callback array.
*
* @zh
- * 滑动器组件事件回调函数。
+ * 滑动器组件滑动事件回调函数数组。
*/
@type([EventHandler])
@tooltip('滑动器组件事件回调函数')