From acceb250f713f994531115e53d97282251b1bf3e Mon Sep 17 00:00:00 2001 From: Will Eastcott Date: Sun, 17 Mar 2024 22:49:03 +0000 Subject: [PATCH 1/5] Improve typing for Anim APIs --- .../anim/controller/anim-controller.js | 124 ++++++++++++++---- .../anim/controller/anim-transition.js | 18 +-- .../components/anim/component-layer.js | 12 +- 3 files changed, 117 insertions(+), 37 deletions(-) diff --git a/src/framework/anim/controller/anim-controller.js b/src/framework/anim/controller/anim-controller.js index ed7f73f7adb..360133fd3bc 100644 --- a/src/framework/anim/controller/anim-controller.js +++ b/src/framework/anim/controller/anim-controller.js @@ -20,6 +20,81 @@ import { * @ignore */ class AnimController { + /** + * @type {Object} + * @private + */ + _states = {}; + + /** + * @type {string[]} + * @private + */ + _stateNames = []; + + /** + * @type {Object} + * @private + */ + _findTransitionsFromStateCache = {}; + + /** + * @type {Object} + * @private + */ + _findTransitionsBetweenStatesCache = {}; + + /** + * @type {string|null} + * @private + */ + _previousStateName = null; + + /** @private */ + _activeStateName = ANIM_STATE_START; + + /** @private */ + _activeStateDuration = 0; + + /** @private */ + _activeStateDurationDirty = true; + + /** @private */ + _playing = false; + + /** + * @type {boolean} + * @private + */ + _activate; + + /** + * @type {AnimTransition[]} + * @private + */ + _transitions; + + /** @private */ + _currTransitionTime = 1; + + /** @private */ + _totalTransitionTime = 1; + + /** @private */ + _isTransitioning = false; + + /** @private */ + _transitionInterruptionSource = ANIM_INTERRUPTION_NONE; + + /** @private */ + _transitionPreviousStates = []; + + /** @private */ + _timeInState = 0; + + /** @private */ + _timeInStateBefore = 0; + /** * Create a new AnimController. * @@ -33,14 +108,13 @@ class AnimController { * once all {@link AnimNodes} are assigned animations. * @param {import('../../../core/event-handler.js').EventHandler} eventHandler - The event * handler which should be notified with anim events. - * @param {Function} findParameter - Retrieves a parameter which is used to control the transition between states. - * @param {Function} consumeTrigger - Used to set triggers back to their default state after they - * have been consumed by a transition. + * @param {Function} findParameter - Retrieves a parameter which is used to control the + * transition between states. + * @param {Function} consumeTrigger - Used to set triggers back to their default state after + * they have been consumed by a transition. */ constructor(animEvaluator, states, transitions, activate, eventHandler, findParameter, consumeTrigger) { this._animEvaluator = animEvaluator; - this._states = {}; - this._stateNames = []; this._eventHandler = eventHandler; this._findParameter = findParameter; this._consumeTrigger = consumeTrigger; @@ -59,23 +133,7 @@ class AnimController { ...transition }); }); - this._findTransitionsFromStateCache = {}; - this._findTransitionsBetweenStatesCache = {}; - this._previousStateName = null; - this._activeStateName = ANIM_STATE_START; - this._activeStateDuration = 0.0; - this._activeStateDurationDirty = true; - this._playing = false; this._activate = activate; - - this._currTransitionTime = 1.0; - this._totalTransitionTime = 1.0; - this._isTransitioning = false; - this._transitionInterruptionSource = ANIM_INTERRUPTION_NONE; - this._transitionPreviousStates = []; - - this._timeInState = 0; - this._timeInStateBefore = 0; } get animEvaluator() { @@ -178,6 +236,11 @@ class AnimController { return this._animEvaluator.assignMask(mask); } + /** + * @param {string} stateName - The name of the state to find. + * @returns {AnimState} The state with the given name. + * @private + */ _findState(stateName) { return this._states[stateName]; } @@ -194,7 +257,14 @@ class AnimController { return null; } - // return all the transitions that have the given stateName as their source state + /** + * Return all the transitions that have the given stateName as their source state. + * + * @param {string} stateName - The name of the state to find transitions from. + * @returns {AnimTransition[]} The transitions that have the given stateName as their source + * state. + * @private + */ _findTransitionsFromState(stateName) { let transitions = this._findTransitionsFromStateCache[stateName]; if (!transitions) { @@ -210,7 +280,15 @@ class AnimController { return transitions; } - // return all the transitions that contain the given source and destination states + /** + * Return all the transitions that contain the given source and destination states. + * + * @param {string} sourceStateName - The name of the source state to find transitions from. + * @param {string} destinationStateName - The name of the destination state to find transitions + * to. + * @returns {AnimTransition[]} The transitions that have the given source and destination states. + * @private + */ _findTransitionsBetweenStates(sourceStateName, destinationStateName) { let transitions = this._findTransitionsBetweenStatesCache[sourceStateName + '->' + destinationStateName]; if (!transitions) { diff --git a/src/framework/anim/controller/anim-transition.js b/src/framework/anim/controller/anim-transition.js index 353b0c2420d..ec699d74ffe 100644 --- a/src/framework/anim/controller/anim-transition.js +++ b/src/framework/anim/controller/anim-transition.js @@ -17,19 +17,19 @@ class AnimTransition { * @param {object} options - Options. * @param {string} options.from - The state that this transition will exit from. * @param {string} options.to - The state that this transition will transition to. - * @param {number} options.time - The duration of the transition in seconds. Defaults to 0. - * @param {number} options.priority - Used to sort all matching transitions in ascending order. - * The first transition in the list will be selected. Defaults to 0. - * @param {object[]} options.conditions - A list of conditions which must pass for this + * @param {number} [options.time] - The duration of the transition in seconds. Defaults to 0. + * @param {number} [options.priority] - Used to sort all matching transitions in ascending + * order. The first transition in the list will be selected. Defaults to 0. + * @param {object[]} [options.conditions] - A list of conditions which must pass for this * transition to be used. Defaults to []. - * @param {number} options.exitTime - If provided, this transition will only be active for the - * exact frame during which the source states progress passes the time specified. Given as a - * normalized value of the source states duration. Values less than 1 will be checked every + * @param {number} [options.exitTime] - If provided, this transition will only be active for + * the exact frame during which the source states progress passes the time specified. Given as + * a normalized value of the source states duration. Values less than 1 will be checked every * animation loop. Defaults to null. - * @param {number} options.transitionOffset - If provided, the destination state will begin + * @param {number} [options.transitionOffset] - If provided, the destination state will begin * playing its animation at this time. Given in normalized time, based on the state's duration * and must be between 0 and 1. Defaults to null. - * @param {string} options.interruptionSource - Defines whether another transition can + * @param {string} [options.interruptionSource] - Defines whether another transition can * interrupt this one and which of the current or previous states transitions can do so. One of * pc.ANIM_INTERRUPTION_*. Defaults to pc.ANIM_INTERRUPTION_NONE. */ diff --git a/src/framework/components/anim/component-layer.js b/src/framework/components/anim/component-layer.js index 4fa5c9780ba..1891599ce73 100644 --- a/src/framework/components/anim/component-layer.js +++ b/src/framework/components/anim/component-layer.js @@ -15,13 +15,15 @@ class AnimComponentLayer { * Create a new AnimComponentLayer instance. * * @param {string} name - The name of the layer. - * @param {object} controller - The controller to manage this layers animations. + * @param {import('../../anim/controller/anim-controller.js').AnimController} controller - The + * controller to manage this layers animations. * @param {import('./component.js').AnimComponent} component - The component that this layer is * a member of. * @param {number} [weight] - The weight of this layer. Defaults to 1. * @param {string} [blendType] - The blend type of this layer. Defaults to {@link ANIM_LAYER_OVERWRITE}. * @param {boolean} [normalizedWeight] - Whether the weight of this layer should be normalized * using the total weight of all layers. + * @ignore */ constructor(name, controller, component, weight = 1, blendType = ANIM_LAYER_OVERWRITE, normalizedWeight = true) { this._name = name; @@ -49,7 +51,7 @@ class AnimComponentLayer { /** * Whether this layer is currently playing. * - * @type {string} + * @type {boolean} */ set playing(value) { this._controller.playing = value; @@ -63,7 +65,7 @@ class AnimComponentLayer { * Returns true if a state graph has been loaded and all states in the graph have been assigned * animation tracks. * - * @type {string} + * @type {boolean} */ get playable() { return this._controller.playable; @@ -81,14 +83,14 @@ class AnimComponentLayer { /** * Returns the previously active state name. * - * @type {string} + * @type {string|null} */ get previousState() { return this._controller.previousStateName; } /** - * Returns the currently active states progress as a value normalized by the states animation + * Returns the currently active state's progress as a value normalized by the state's animation * duration. Looped animations will return values greater than 1. * * @type {number} From 85106fed25aaeed6a93262fe450b022ee48e5826 Mon Sep 17 00:00:00 2001 From: Will Eastcott Date: Sun, 17 Mar 2024 22:56:37 +0000 Subject: [PATCH 2/5] Better typing --- src/framework/components/anim/component-layer.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/framework/components/anim/component-layer.js b/src/framework/components/anim/component-layer.js index 1891599ce73..01c4f735ebb 100644 --- a/src/framework/components/anim/component-layer.js +++ b/src/framework/components/anim/component-layer.js @@ -309,7 +309,7 @@ class AnimComponentLayer { * animation should be associated with. Each section of a blend tree path is split using a * period (`.`) therefore state names should not include this character (e.g "MyStateName" or * "MyStateName.BlendTreeNode"). - * @param {object} animTrack - The animation track that will be assigned to this state and + * @param {AnimTrack} animTrack - The animation track that will be assigned to this state and * played whenever this state is active. * @param {number} [speed] - Update the speed of the state you are assigning an animation to. * Defaults to 1. From 366e975f3776f30c2cce0fec140ae6d3b1e2e313 Mon Sep 17 00:00:00 2001 From: Will Eastcott Date: Sun, 17 Mar 2024 23:03:10 +0000 Subject: [PATCH 3/5] Lint fix --- src/framework/anim/controller/anim-controller.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/framework/anim/controller/anim-controller.js b/src/framework/anim/controller/anim-controller.js index 360133fd3bc..0744c4ee2eb 100644 --- a/src/framework/anim/controller/anim-controller.js +++ b/src/framework/anim/controller/anim-controller.js @@ -62,7 +62,7 @@ class AnimController { /** @private */ _playing = false; - /** + /** * @type {boolean} * @private */ From bbe2f4039f4f4167fca890736ad97ef8bcb05a8a Mon Sep 17 00:00:00 2001 From: Will Eastcott Date: Sun, 17 Mar 2024 23:13:45 +0000 Subject: [PATCH 4/5] More use of class fields --- .../components/anim/component-layer.js | 56 +++++++++++++++++-- 1 file changed, 51 insertions(+), 5 deletions(-) diff --git a/src/framework/components/anim/component-layer.js b/src/framework/components/anim/component-layer.js index 01c4f735ebb..879664b74ef 100644 --- a/src/framework/components/anim/component-layer.js +++ b/src/framework/components/anim/component-layer.js @@ -11,6 +11,57 @@ import { ANIM_LAYER_OVERWRITE } from '../../anim/controller/constants.js'; * @category Animation */ class AnimComponentLayer { + /** + * @type {string} + * @private + */ + _name; + + /** + * @type {import('../../anim/controller/anim-controller.js').AnimController} + * @private + */ + _controller; + + /** + * @type {import('./component.js').AnimComponent} + * @private + */ + _component; + + /** + * @type {number} + * @private + */ + _weight; + + /** + * @type {string} + * @private + */ + _blendType; + + /** + * @type {boolean} + * @private + */ + _normalizedWeight; + + /** @private */ + _mask = null; + + /** @private */ + _blendTime = 0; + + /** @private */ + _blendTimeElapsed = 0; + + /** @private */ + _startingWeight = 0; + + /** @private */ + _targetWeight = 0; + /** * Create a new AnimComponentLayer instance. * @@ -32,11 +83,6 @@ class AnimComponentLayer { this._weight = weight; this._blendType = blendType; this._normalizedWeight = normalizedWeight; - this._mask = null; - this._blendTime = 0; - this._blendTimeElapsed = 0; - this._startingWeight = 0; - this._targetWeight = 0; } /** From 9ca9dfe54d8c706ddf262c33adbb41e4749aef47 Mon Sep 17 00:00:00 2001 From: Will Eastcott Date: Sun, 17 Mar 2024 23:15:57 +0000 Subject: [PATCH 5/5] Remove unused _normalizedWeight param --- src/framework/components/anim/component-layer.js | 11 +---------- 1 file changed, 1 insertion(+), 10 deletions(-) diff --git a/src/framework/components/anim/component-layer.js b/src/framework/components/anim/component-layer.js index 879664b74ef..d9162a032f3 100644 --- a/src/framework/components/anim/component-layer.js +++ b/src/framework/components/anim/component-layer.js @@ -41,12 +41,6 @@ class AnimComponentLayer { */ _blendType; - /** - * @type {boolean} - * @private - */ - _normalizedWeight; - /** @private */ _mask = null; @@ -72,17 +66,14 @@ class AnimComponentLayer { * a member of. * @param {number} [weight] - The weight of this layer. Defaults to 1. * @param {string} [blendType] - The blend type of this layer. Defaults to {@link ANIM_LAYER_OVERWRITE}. - * @param {boolean} [normalizedWeight] - Whether the weight of this layer should be normalized - * using the total weight of all layers. * @ignore */ - constructor(name, controller, component, weight = 1, blendType = ANIM_LAYER_OVERWRITE, normalizedWeight = true) { + constructor(name, controller, component, weight = 1, blendType = ANIM_LAYER_OVERWRITE) { this._name = name; this._controller = controller; this._component = component; this._weight = weight; this._blendType = blendType; - this._normalizedWeight = normalizedWeight; } /**