sync #3d-tasks/issues/3962 (#7232)

* sync #3d-tasks/issues/3962

#5598
#6575
#6333
#4003
#4240
#5444
#5178
#5656
#5672
#3515
#3617
#3802
#4152

* refine code

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
 

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 函数，该参数是回调函数的参数值（可不填）。
      *

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;
 

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;
 

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();
+
+/**
+ * @en
+ * This is a Game instance.
+ * @zh
+ * 这是一个 Game 类的实例，包含游戏主体信息并负责驱动游戏的游戏对象。
+ */
+export const game = legacyCC.game = new Game();

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) {

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) {

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 {

cocos/core/scheduler.ts

@@ -683,10 +683,10 @@ export class Scheduler extends System {
 
     /**
      * @en
-     * Unschedules a callback for a callback and a given target.<br>
+     * Unschedules a callback for a callback and a given target.
      * If you want to unschedule the "update", use `unscheduleUpdate()`
      * @zh
-     * 根据指定的回调函数和调用对象。<br>
+     * 取消指定对象定时器。
      * 如果需要取消 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
      * 取消所有对象的所有定时器，包括系统定时器。<br/>
-     * 不用调用此函数，除非你确定你在做什么。
+     * 不要调用此函数，除非你确定你在做什么。
      */
     public unscheduleAll (){
         this.unscheduleAllWithMinPriority(legacyCC.Scheduler.PRIORITY_SYSTEM);

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
- * 按钮组件。可以被按下,或者点击。<br/>
+ * 按钮组件。可以被按下，或者点击。
  *
- * 按钮可以通过修改 Transition 来设置按钮状态过渡的方式：<br/>
- *   - `Button.Transition.NONE`   // 不做任何过渡<br/>
- *   - `Button.Transition.COLOR`  // 进行颜色之间过渡<br/>
- *   - `Button.Transition.SPRITE` // 进行精灵之间过渡<br/>
- *   - `Button.Transition.SCALE` // 进行缩放过渡<br/>
+ * 按钮可以通过修改 Transition 来设置按钮状态过渡的方式：
+ *
+ *   - Button.Transition.NONE   // 不做任何过渡
+ *   - Button.Transition.COLOR  // 进行颜色之间过渡
+ *   - Button.Transition.SPRITE // 进行精灵之间过渡
+ *   - Button.Transition.SCALE // 进行缩放过渡
  *
  * 按钮可以绑定事件（但是必须要在按钮的 Node 上才能绑定事件）：<br/>
- *   // 以下事件可以在全平台上都触发<br/>
- *   - `Node.EventType.TOUCH_START`  // 按下时事件<br/>
- *   - `Node.EventType.TOUCH_Move`   // 按住移动后事件<br/>
- *   - `Node.EventType.TOUCH_END`    // 按下后松开后事件<br/>
- *   - `Node.EventType.TOUCH_CANCEL` // 按下取消事件<br/>
- *   // 以下事件只在 PC 平台上触发<br/>
- *   - `Node.EventType.MOUSE_DOWN`  // 鼠标按下时事件<br/>
- *   - `Node.EventType.MOUSE_MOVE`  // 鼠标按住移动后事件<br/>
- *   - `Node.EventType.MOUSE_ENTER` // 鼠标进入目标事件<br/>
- *   - `Node.EventType.MOUSE_LEAVE` // 鼠标离开目标事件<br/>
- *   - `Node.EventType.MOUSE_UP`    // 鼠标松开事件<br/>
- *   - `Node.EventType.MOUSE_WHEEL` // 鼠标滚轮事件<br/>
+ * 以下事件可以在全平台上都触发：
+ *
+ *   - 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

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,
     /**

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('滑动器组件事件回调函数')