Documentation added. Standard renamed to StandardStages to be more explicit

Author: krispya

example/src/demos/Update.tsx

@@ -3,7 +3,7 @@ import {
   Canvas,
   FixedStage,
   Stage,
-  Standard,
+  StandardStages as Standard,
   useFrame,
   useThree,
   useUpdate,

packages/fiber/src/core/hooks.tsx

@@ -4,7 +4,7 @@ import { StateSelector, EqualityChecker } from 'zustand'
 import { suspend, preload, clear } from 'suspend-react'
 import { context, RootState, RenderCallback } from './store'
 import { buildGraph, ObjectMap, is, useMutableCallback, useIsomorphicLayoutEffect } from './utils'
-import { UpdateCallback } from './stages'
+import { Stages, UpdateCallback } from './stages'
 
 export interface Loader<T> extends THREE.Loader {
   load(
@@ -52,11 +52,18 @@ export function useFrame(callback: RenderCallback, renderPriority: number = 0):
   return null
 }
 
-export function useUpdate(callback: UpdateCallback, stage: string = 'update') {
+/**
+ * Executes a callback in a given update stage.
+ * The default stages can be accessed through the Stages enum.
+ */
+export function useUpdate(callback: UpdateCallback, stage: string = Stages.Update) {
   const store = useStore()
   const stagesMap = store.getState().internal.stagesMap
+  // Memoize ref
   const ref = useMutableCallback(callback)
+  // Throw an error if a stage does not exist
   if (!stagesMap[stage]) throw `A '${stage}' stage does not exist.`
+  // Subscribe on mount, unsubscribe on unmount
   useIsomorphicLayoutEffect(() => stagesMap[stage].add(ref, store), [stage])
 }
 

packages/fiber/src/core/index.tsx

@@ -32,7 +32,7 @@ import {
   setDeep,
 } from './utils'
 import { useStore } from './hooks'
-import { Stage, Standard, StandardStages } from './stages'
+import { Stage, StandardLifecycle, StandardStages } from './stages'
 
 const roots = new Map<Element, Root>()
 const { invalidate, advance } = createLoop(roots)
@@ -125,10 +125,10 @@ const createStages = (stages: Stage[] | undefined, store: UseBoundStore<RootStat
   let subscribers: Subscription[]
   let subscription: Subscription
 
-  stages = stages ?? StandardStages
+  stages = stages ?? StandardLifecycle
 
-  if (!stages.includes(Standard.Update)) throw 'The Standard.Update stage is required for R3F.'
-  if (!stages.includes(Standard.Render)) throw 'The Standard.Render stage is required for R3F.'
+  if (!stages.includes(StandardStages.Update)) throw 'The StandardStages.Update stage is required for R3F.'
+  if (!stages.includes(StandardStages.Render)) throw 'The StandardStages.Render stage is required for R3F.'
 
   state.set(({ internal }) => ({ internal: { ...internal, stages: stages! } }))
   for (const stage of stages) {

packages/fiber/src/core/stages.ts

@@ -10,8 +10,14 @@ export type UpdateCallbackRef = MutableRefObject<UpdateCallback>
 type Store = UseBoundStore<RootState, StoreApi<RootState>>
 export type UpdateSubscription = { ref: UpdateCallbackRef; store: Store }
 
-export type FixedStageOptions = { fixedStep?: number; maxSubSteps?: number }
-
+export type FixedStageOptions = { fixedStep?: number; maxSubsteps?: number }
+export type FixedStageProps = { fixedStep: number; maxSubsteps: number; accumulator: number; alpha: number }
+
+/**
+ * Class representing a stage that updates every frame.
+ * Stages are used to build a lifecycle of effects for an app's frameloop.
+ * @param {string} name - Name of the stage.
+ */
 export class Stage {
   name: string
   subscribers: UpdateSubscription[]
@@ -21,6 +27,11 @@ export class Stage {
     this.subscribers = []
   }
 
+  /**
+   * Executes all callback subscriptions on the stage.
+   * @param {number} delta - Delta time between frame calls.
+   * @param {THREE.XRFrame | undefined} [frame] - The XR frame if it exists.
+   */
   frame(delta: number, frame?: THREE.XRFrame | undefined) {
     const subs = this.subscribers
 
@@ -29,6 +40,12 @@ export class Stage {
     }
   }
 
+  /**
+   * Adds a callback subscriber to the stage.
+   * @param {UpdateCallbackRef} ref - The mutable callback reference.
+   * @param {Store} store - The store to be used with the callback execution.
+   * @returns {() => void} A function to remove the subscription.
+   */
   add(ref: UpdateCallbackRef, store: Store) {
     this.subscribers.push({ ref, store })
 
@@ -40,9 +57,17 @@ export class Stage {
   }
 }
 
-// Using Unity's default here.
+// Using Unity's fixedStep default.
 const FPS_50 = 1 / 50
 
+/**
+ * Class representing a stage that updates every frame at a fixed rate.
+ * @param {string} name - Name of the stage.
+ * @param {FixedStageOptions} [options] - Options for the fixed stage.
+ * @param {number} [options.fixedStep] - Fixed step rate.
+ * @param {number} [options.maxSubsteps] - Maximum number of substeps.
+ * @extends Stage
+ */
 export class FixedStage extends Stage {
   private fixedStep: number
   private maxSubsteps: number
@@ -58,6 +83,11 @@ export class FixedStage extends Stage {
     this.alpha = 0
   }
 
+  /**
+   * Executes all callback subscriptions on the stage.
+   * @param {number} delta - Delta time between frame calls.
+   * @param {THREE.XRFrame | undefined} [frame] - The XR frame if it exists.
+   */
   frame(delta: number, frame?: THREE.XRFrame | undefined) {
     const initialTime = performance.now()
     let substeps = 0
@@ -77,19 +107,33 @@ export class FixedStage extends Stage {
     }
 
     // The accumulator will only be larger than the fixed step if we had to
-    // bail early due to hitting the max substep limit. In that case, we want to
-    // shave off the excess so we don't fall behind next frame.
+    // bail early due to hitting the max substep limit or execution time lagging.
+    // In that case, we want to shave off the excess so we don't fall behind next frame.
     this.accumulator = this.accumulator % this.fixedStep
     this.alpha = this.accumulator / this.fixedStep
   }
 
+  /**
+   * Set the fixed stage properties.
+   * @param {FixedStageOptions} options - Options for the fixed stage.
+   * @param {number} [options.fixedStep] - Fixed step rate.
+   * @param {number} [options.maxSubsteps] - Maximum number of substeps.
+   */
   set(options: FixedStageOptions) {
-    const { fixedStep, maxSubSteps } = options
+    const { fixedStep, maxSubsteps } = options
     if (fixedStep) this.fixedStep = fixedStep
-    if (maxSubSteps) this.maxSubsteps = maxSubSteps
+    if (maxSubsteps) this.maxSubsteps = maxSubsteps
   }
 
-  get() {
+  /**
+   * Get the fixed stage properties.
+   * @returns {FixedStageProps} props The fixed stage properties.
+   * @returns {number} props.fixedStep The fixed step rate.
+   * @returns {number} props.maxSubsteps The maximum number of substeps.
+   * @returns {number} props.accumulator The time left over in the accumulator.
+   * @returns {number} props.alpha The ratio of remaining time and step size. Useful for interpolation.
+   */
+  get(): FixedStageProps {
     return {
       fixedStep: this.fixedStep,
       maxSubsteps: this.maxSubsteps,
@@ -106,8 +150,8 @@ const Late = new Stage('late')
 const Render = new Stage('render')
 const After = new Stage('after')
 
-export const Standard = { Early, Fixed, Update, Late, Render, After }
-export const StandardStages = [Early, Fixed, Update, Late, Render, After]
+export const StandardStages = { Early, Fixed, Update, Late, Render, After }
+export const StandardLifecycle = [Early, Fixed, Update, Late, Render, After]
 
 export enum Stages {
   Early = 'early',

packages/fiber/src/core/store.ts

@@ -303,11 +303,20 @@ const createStore = (
 
         // Updates
         active: false,
-        priority: 0,
         frames: 0,
+        /**
+         * The ordered stages defining the lifecycle.
+         */
         stages: [],
+        /**
+         * The stages map, where the key is the stage name and the value is the stage.
+         */
         stagesMap: {},
+        /**
+         * The max delta time between two frames.
+         */
         maxDelta: 1 / 10,
+        priority: 0,
         subscribe: (
           ref: React.MutableRefObject<RenderCallback>,
           priority: number,

packages/fiber/src/index.tsx

@@ -17,4 +17,4 @@ export type { ObjectMap, Camera } from './core/utils'
 export * from './web/Canvas'
 export { createPointerEvents as events } from './web/events'
 export * from './core'
-export { Stage, FixedStage, Standard, Stages } from './core/stages'
+export { Stage, FixedStage, StandardStages, Stages } from './core/stages'