refactor: better time management for engine loop

Author: ColinEspinas

src/core/Engine.ts

@@ -1,4 +1,5 @@
 import type { EngineOptions } from '../options/EngineOptions'
+import { EngineError } from '../errors/EngineError'
 import type { OuterNode } from './OuterNode'
 import type { TreeNode } from './TreeNode'
 import { Time } from './Time'
@@ -12,13 +13,9 @@ export class Engine {
    */
   private _options: EngineOptions
   /**
-   * Engine container element.
+   * Engine DOM container element.
    */
   private _container: HTMLElement
-  /**
-   * Root node of the engine's graph.
-   */
-  public rootNode: TreeNode
   /**
    * Engine's attached systems.
    */
@@ -27,6 +24,10 @@ export class Engine {
    * Engine's time utility.
    */
   private _time: Time = new Time()
+  /**
+   * Root node of the engine's graph.
+   */
+  public rootNode: TreeNode | undefined
 
   /**
    * Get engine's options.
@@ -64,7 +65,7 @@ export class Engine {
       framerate: null,
       ...options,
     }
-    this._container = document.querySelector(this._options.container)
+    this._container = document.querySelector(this._options.container as string) as HTMLElement
     this.init()
   }
 
@@ -79,7 +80,7 @@ export class Engine {
   public run(): void {
     // Check if root node exists before loading.
     if (!this.rootNode) {
-      throw new Error('No root node given to engine, cannot run.')
+      throw new EngineError(this, 'ENGINE:FAILURE', 'No root node given to engine, cannot run.')
     }
     // Load systems.
     this.systems.forEach((system) => {
@@ -97,21 +98,26 @@ export class Engine {
    * to fix the timestep for fixed update loops (useful for physics and user interactions).
    */
   protected step(now: number): void {
+    if (!this.rootNode) {
+      throw new EngineError(this, 'ENGINE:FAILURE', 'No root node given to engine, cannot run.')
+    }
     // Update delta and last frame time
-    this.time.updateDelta(now)
-    this.time.updateLast()
+    this.time.update(now)
     // Fix timestep of fixedStep methods
     this.time.fixTimestep(() => {
+      if (!this.rootNode) {
+        throw new EngineError(this, 'ENGINE:FAILURE', 'No root node given to engine, cannot run.')
+      }
       this.systems.forEach((system) => {
-        Promise.resolve().then(() => system.fixedStep())
+        system.fixedStep()
       })
-      Promise.resolve().then(() => this.rootNode.fixedStep())
+      this.rootNode.fixedStep()
     })
     // Do non fixed steps
     this.systems.forEach((system) => {
-      system.step()
+      system.step(this.time.delta)
     })
-    this.rootNode.step()
+    this.rootNode.step(this.time.delta)
     // Request next step
     requestAnimationFrame(this.step.bind(this))
   }

src/core/InnerNode.ts

@@ -1,3 +1,4 @@
+import { EngineError } from '../errors/EngineError'
 import type { Engine } from './Engine'
 import { TreeNode } from './TreeNode'
 
@@ -13,14 +14,14 @@ export class InnerNode extends TreeNode {
   /**
    * Node's children nodes.
    */
-  protected children: TreeNode[]
+  protected _children: TreeNode[]
 
   /**
    * Setup children and calls onCreate method.
    */
   constructor(parent: TreeNode | Engine) {
     super(parent)
-    this.children = []
+    this._children = []
     this.onCreate()
   }
 
@@ -31,11 +32,11 @@ export class InnerNode extends TreeNode {
    * @sealed
    */
   public add(node: TreeNode): number {
-    this.children.push(node)
+    this._children.push(node)
     // Load the added node if added after loading.
-    if (this.isLoaded)
+    if (this._isLoaded)
       node.load()
-    return this.children.length
+    return this._children.length
   }
 
   /**
@@ -46,7 +47,7 @@ export class InnerNode extends TreeNode {
    */
   public remove(node: TreeNode): TreeNode {
     let removedNode
-    this.children = this.children.filter((n: TreeNode) => {
+    this._children = this._children.filter((n: TreeNode) => {
       // Unloads and filters the given node out.
       if (n.id === node.id) {
         removedNode = n
@@ -55,6 +56,8 @@ export class InnerNode extends TreeNode {
       }
       return true
     })
+    if (!removedNode)
+      throw new EngineError(this._engine, 'NODE:FAILURE', 'The node you tried to remove is not a child of this node.')
     return removedNode
   }
 
@@ -67,10 +70,10 @@ export class InnerNode extends TreeNode {
    */
   public load(): void {
     this.onLoad()
-    for (let i = 0, len = this.children.length; i !== len; ++i) {
-      this.children[i].load()
+    for (let i = 0, len = this._children.length; i !== len; ++i) {
+      this._children[i].load()
     }
-    this.isLoaded = true
+    this._isLoaded = true
   }
 
   /**
@@ -80,10 +83,10 @@ export class InnerNode extends TreeNode {
    * Calls the `onStep` method and children's `step` methods.
    * @sealed
    */
-  public step(): void {
-    this.onStep()
-    for (let i = 0, len = this.children.length; i !== len; ++i) {
-      this.children[i].step()
+  public step(delta: number): void {
+    this.onStep(delta)
+    for (let i = 0, len = this._children.length; i !== len; ++i) {
+      this._children[i].step(delta)
     }
   }
 
@@ -96,8 +99,8 @@ export class InnerNode extends TreeNode {
    */
   public fixedStep(): void {
     this.onFixedStep()
-    for (let i = 0, len = this.children.length; i !== len; ++i) {
-      this.children[i].fixedStep()
+    for (let i = 0, len = this._children.length; i !== len; ++i) {
+      this._children[i].fixedStep()
     }
   }
 
@@ -110,10 +113,10 @@ export class InnerNode extends TreeNode {
    */
   public unload(): void {
     this.onUnload()
-    for (let i = 0, len = this.children.length; i !== len; ++i) {
-      this.children[i].unload()
+    for (let i = 0, len = this._children.length; i !== len; ++i) {
+      this._children[i].unload()
     }
-    this.isLoaded = false
+    this._isLoaded = false
   }
 
   /**
@@ -138,7 +141,8 @@ export class InnerNode extends TreeNode {
    * this function is to be implemented when needed.
    * @virtual
    */
-  protected onStep(): void { }
+  // eslint-disable-next-line unused-imports/no-unused-vars
+  protected onStep(delta: number): void { }
 
   /**
    * Called by the parent node at each fixed step of the loop,

src/core/OuterNode.ts

@@ -1,3 +1,4 @@
+import { EngineError } from '../errors/EngineError'
 import type { Engine } from './Engine'
 import { TreeNode } from './TreeNode'
 
@@ -21,7 +22,7 @@ export class OuterNode extends TreeNode {
    * @sealed
    */
   public add(): number {
-    throw new Error('You tried to add a child to an outer node. Outer nodes cannot have children.')
+    throw new EngineError(this._engine, 'NODE:FAILURE', 'You tried to add a child to an outer node. Outer nodes cannot have children.')
   }
 
   /**
@@ -30,7 +31,7 @@ export class OuterNode extends TreeNode {
    * @sealed
    */
   public remove(): TreeNode {
-    throw new Error('You tried to remove a child to an outer node. Outer nodes cannot have children.')
+    throw new EngineError(this._engine, 'NODE:FAILURE', 'You tried to remove a child to an outer node. Outer nodes cannot have children.')
   }
 
   /**
@@ -42,7 +43,7 @@ export class OuterNode extends TreeNode {
    */
   public load(): void {
     this.onLoad()
-    this.isLoaded = true
+    this._isLoaded = true
   }
 
   /**
@@ -52,8 +53,8 @@ export class OuterNode extends TreeNode {
    * Calls the `onStep` method.
    * @sealed
    */
-  public step(): void {
-    this.onStep()
+  public step(delta: number): void {
+    this.onStep(delta)
   }
 
   /**
@@ -76,7 +77,7 @@ export class OuterNode extends TreeNode {
    */
   public unload(): void {
     this.onUnload()
-    this.isLoaded = false
+    this._isLoaded = false
   }
 
   /**
@@ -101,7 +102,8 @@ export class OuterNode extends TreeNode {
    * this method is to be implemented when needed.
    * @virtual
    */
-  protected onStep(): void { }
+  // eslint-disable-next-line unused-imports/no-unused-vars
+  protected onStep(delta: number): void { }
 
   /**
    * Called by the parent node at each fixed step of the loop,

src/core/Time.ts

@@ -2,57 +2,46 @@ export class Time {
   /**
    * Start of the engine's step.
    */
-  private now: number
+  private _now: number = performance.now()
   /**
-   * Delta time between frame.
+   * Delta time between frame in seconds.
    */
   private _delta: number = 0
   /**
    * Accumulator used to store time between frames
    */
-  private accumulator: number = 0
+  private _accumulator: number = 0
   /**
    * Time of the last engine's step.
    */
-  private last: number = performance.now()
+  private _last: number = performance.now()
   /**
    * Slow motion scaling factor.
    */
   private _slow: number = 1
   /**
    * Target framerate of the engine.
    */
-  private targetFramerate: number = 60
+  private _targetFramerate: number = 60
   /**
    * Current framerate in frames per second.
    */
-  private fps: number
-  /**
-   * Ideal time of a step.
-   */
-  private _timestep: number = (1 / this.targetFramerate) * this.slow
+  private _fps: number = 0
 
   /**
-   * Get engine's delta time.
+   * Get engine's delta time in seconds.
    */
   public get delta(): number { return this._delta }
 
   /**
-   * Get engine's timestep.
+   * Get the current engine's time for a step in seconds (this is the ideal time of a frame).
    */
-  public get timestep(): number { return this._timestep }
+  public get timestep(): number { return (1 / this._targetFramerate) * this._slow }
 
   /**
    * Get current framerate in frames per second.
    */
-  public get framerate(): number { return this.fps }
-  /**
-   * Set an ideal maximum framerate in frames per second.
-   */
-  public set framerate(target: number) {
-    this.targetFramerate = target
-    this._timestep = (1 / this.targetFramerate) * this.slow
-  }
+  public get framerate(): number { return this._fps }
 
   /**
    * Get slow scaling factor.
@@ -63,39 +52,39 @@ export class Time {
    */
   public set slow(value: number) {
     this._slow = value
-    this._timestep = (1 / this.targetFramerate) * this.slow
   }
 
-  /**
-   * Updates the delta time, used by the engine's step loop.
-   */
-  public updateDelta(now?: number) {
-    this.now = now ?? performance.now()
-    this._delta = (this.now - this.last) / 1000
-    this.accumulator += this._delta
-    this.fps = 1 / this._delta
+  public get targetFramerate(): number { return this._targetFramerate }
+
+  public set targetFramerate(value: number) {
+    this._targetFramerate = value
   }
 
   /**
-   * Updates the time of the last update.
+   * Updates delta time and related variables, used by the engine's step loop.
    */
-  public updateLast() {
-    this.last = this.now
+  public update(now?: number) {
+    this._now = now ?? performance.now()
+    this._delta = (this._now - this._last) / 1000
+    this._last = this._now
+    this._accumulator += this._delta
+    this._fps = 1 / this._delta
   }
 
   /**
    * Fixes the timestep of a given function during the engine's step loop.
    * Used in engine's `step` method to make fixed steps.
    * @param callback
    */
-  public fixTimestep(callback: (timestep?: number) => void) {
-    const updateStepsCount = 0
-    while (this.accumulator >= this._timestep) {
-      callback(this._timestep)
-      this.accumulator -= this._timestep
+  public fixTimestep(callback: () => void) {
+    let updateStepsCount = 0
+    while (this._accumulator >= this.timestep) {
+      callback()
+      this._accumulator -= this.timestep
+      ++updateStepsCount
       // To prevent spiral of death
       if (updateStepsCount >= 240) {
-        this.accumulator = 0
+        this._accumulator = 0
         break
       }
     }