brick-engine-js 1.0.21 → 1.0.23

package/dist/types/bootstrap.d.ts

@@ -2,28 +2,29 @@ import p5 from 'p5';
 import Game from './core/Game';
 import GameView from './view/GameView';
 /**
- * Represents a constructor for a game class.
+ * Defines the strict constructor signature for Client games booting via the Engine.
  *
  * @callback ClientGameConstructor
- * @param {p5} p - The p5 instance.
- * @param {GameView} view - The game view instance.
- * @returns {Game} A new game instance.
+ * @param {p5} p - The core rendering context pointer injected at runtime.
+ * @param {GameView} view - The specifically built UI configuration context.
+ * @returns {Game} A newly instantiated concrete subclass encompassing all module logic.
  */
 type ClientGameConstructor = new (view: GameView) => Game;
 /**
- * Updates the currently active game in the engine's execution loop.
+ * Hotswaps the persistent engine tracking pointer dictating logic execution loops.
  *
- * @param {Game} game - The new game instance to become active.
+ * @param {Game} game - The fully instantiated class implementing custom module rules.
+ * @returns {void} Returns nothing.
  */
 export declare function setActiveGame(game: Game): void;
 /**
- * Bootstraps the brick engine and initializes the game.
+ * Orchestrating structural point of initialization isolating strict client code execution.
  *
- * This is the main entry point for the engine's execution. It creates a new p5 instance,
- * initializes the view, and sets up the initial game provided by the caller.
+ * Acts as the absolute architectural start for the engine lifecycle. It isolates complex P5.js
+ * canvas injection, internal context caching, and DOM viewport creation away from actual Game logic.
  *
- * @param {ClientGameConstructor} ClientGame - The constructor of the game to be loaded.
- * @returns {p5} The p5 instance.
+ * @param {ClientGameConstructor} ClientGame - The non-instantiated class definition targeted.
+ * @returns {p5} The successfully built processing sketch mapping logic safely onto the web document.
  */
 export declare function bootstrap(ClientGame: ClientGameConstructor): p5;
 export {};

package/dist/types/core/Game.d.ts

@@ -3,10 +3,11 @@ import { Initializable } from './types/Interfaces';
 import { GameModules } from './types/Types';
 import p5 from 'p5';
 /**
- * Base abstract class for the game.
+ * The Central integration boundary encapsulating physical logic away from native visual outputs.
  *
- * It manages the game loop, initialization of core modules, and integration with p5.js.
- * All game logic should be implemented in subclasses by overriding `processTick` and `processFrame`.
+ * Implements the {@link Initializable} configuration pipeline orchestrating completely synchronous
+ * frame drawing metrics while processing isolated state iterations without corrupting data models
+ * dynamically mapped across various internal UI states.
  */
 export default abstract class Game implements Initializable {
     protected _view: GameView;
@@ -14,91 +15,97 @@ export default abstract class Game implements Initializable {
     private _initialStateSnapshot;
     private _gameId;
     /**
-     * Gets the game ID
+     * Returns the strict string identifier binding data persistently.
+     *
+     * @returns {string} The namespace mapped internally.
      */
     get gameId(): string;
     /**
-     * Sets the game ID
+     * Sets the application ID establishing persistent memory keys.
+     *
+     * @param {string} id - The string namespace saving bounds.
+     * @returns {void} Returns nothing.
      */
     set gameId(id: string);
     /**
-     * Creates an instance of the Game.
+     * Constructs the primary controller wrapping native rendering canvases into controlled pipelines.
      *
-     * @param {p5} p - The p5 instance.
-     * @param {GameView} view - The view strategy associated with this game.
+     * @param {GameView} view - The securely decoupled graphical pointer rendering the root body.
      */
     constructor(view: GameView);
     /**
-     * Gets the game view.
+     * Yields strictly controlled visibility access to layout injections.
      *
-     * @returns {GameView} The game view instance.
+     * @returns {GameView} The configured view instance formatting user HTML constraints.
      */
     get view(): GameView;
     /**
-     * Gets the game modules.
+     * Yields fully configured physics, inputs, and drawing context tools dynamically mapped.
      *
-     * @returns {GameModules} The collection of initialized game modules.
+     * @returns {GameModules} A secure aggregate object pointer.
      */
     get modules(): GameModules;
     /**
-     * Gets the p5 instance.
+     * Exposes hardware-accelerated processing calls indirectly via Context bounds.
      *
-     * @returns {p5} The p5 instance.
+     * @returns {p5} The active executing instance map.
      */
     get p(): p5;
     /**
-     * Sets up the game, initializing all modules and viewing components.
-     * Called automatically by the engine key sequence.
+     * Triggers sequential logic parsing across dynamically subscribed execution containers internally.
+     *
+     * Internally synchronizes active memory payloads tracking initialization boundaries automatically.
      *
-     * Internally calls `setupGame()` and then `captureInitialState()`.
-     * This means that all subclass properties (including those initialized in `setupGame`)
-     * are captured as the initial state for the resetting mechanism.
+     * @returns {void} Returns nothing.
      */
     setup(): void;
     /**
-     * Main draw loop, called by p5.js.
-     * Handles time updates, logic ticks, and rendering.
+     * Loops mathematically calculating pixel mutations exactly and logically evaluating system limits.
+     *
+     * @returns {void} Returns nothing.
      */
     draw(): void;
     /**
-     * Destroys the game instance, cleaning up all event listeners and stopping the loop.
-     * Call this before switching to another game or when the game is no longer needed.
+     * Orchestrates destruction callbacks erasing references blocking memory sweeps globally.
+     *
+     * @returns {void} Returns nothing.
      */
     destroy(): void;
     /**
-     * Resets the game to its initial state.
-     * This method is called by the reset event handler and should be used to restore the game to its initial state.
+     * Fires internal overrides mutating internal physics states towards a neutral base metric safely.
+     *
+     * @returns {void} Returns nothing.
      */
     reset(): void;
     /**
-     * Abstract method for processing game logic.
-     * Called every tick, but ONLY when the game is in the 'playing' state.
+     * Subclass abstract delegator resolving physics mathematically based directly on relative speeds.
      *
-     * @param {number} deltaTime - Time elapsed since last tick.
+     * @param {number} deltaTime - Fast ticking number representation capturing elapsed frametimes safely.
+     * @returns {void} Returns nothing.
      */
     abstract update(deltaTime: number): void;
     /**
-     * Abstract method for processing visual frames.
-     * Called every frame (depending on frameInterval).
+     * Subclass abstract delegator dispatching independent geometry outputs onto the physical UI constraints.
+     *
+     * @returns {void} Returns nothing.
      */
     abstract render(): void;
     /**
-     * Abstract method for setting up the game specific logic.
-     * Called after the game modules are initialized.
+     * Subclass abstract delegator establishing customized rules tracking specific bounds mathematically.
      *
-     * Note: All initial properties should be fully assigned here,
-     * as `captureInitialState()` is invoked immediately after this method,
-     * taking a snapshot for the reset mechanism.
+     * @returns {void} Returns nothing.
      */
     abstract setupGame(): void;
     /**
-     * Abstract method for drawing the Title Screen (Welcome).
-     * Called when the game is ON but not yet STARTED.
+     * Subclass abstract delegator dispatching independent UI strings safely evaluating un-started limits.
+     *
+     * @returns {void} Returns nothing.
      */
     abstract drawTitleScreen(): void;
     /**
-     * Abstract method for drawing the Game Over Screen.
-     * Called when the game is in GAME OVER state.
+     * Subclass abstract delegator dispatching independent UI strings safely evaluating finished bounds.
+     *
+     * @returns {void} Returns nothing.
      */
     abstract drawGameOverScreen(): void;
 }

package/dist/types/core/InitialStateSnapshot.d.ts

@@ -1,19 +1,31 @@
+/**
+ * Architectural utility strictly handling transparent auto-save points for custom class boundaries.
+ *
+ * Acts as an agnostic cloning proxy safely evaluating and storing external state payloads without
+ * developers writing boilerplate serialization functions inside native subclasses each time.
+ */
 export default class InitialStateSnapshot {
     private _initialState;
     private _baseProperties;
     /**
-     * Captures the base properties of the instance before any custom client properties are added.
-     * @param instance The object instance to extract keys from.
+     * Caches native structure references dictating immutable engine properties to ignore visually.
+     *
+     * @param {object} instance - The internal unpopulated layout.
+     * @returns {void} Returns nothing.
      */
     captureBaseProperties(instance: object): void;
     /**
-     * Stores the initial state of custom client properties.
-     * @param instance The object instance containing custom properties.
+     * Caches a fully deep-cloned structural reference encapsulating foreign client properties exactly.
+     *
+     * @param {object} instance - The populated concrete object class.
+     * @returns {void} Returns nothing.
      */
     captureInitialState(instance: object): void;
     /**
-     * Restores the captured custom properties back to the instance.
-     * @param instance The object instance to restore properties onto.
+     * Re-assigns the securely cloned caching snapshot values strictly bypassing getter mutation restrictions.
+     *
+     * @param {object} instance - The active object intended to be hard reset entirely.
+     * @returns {void} Returns nothing.
      */
     restoreInitialState(instance: object): void;
 }

package/dist/types/core/context/RendererContext.d.ts

@@ -1,25 +1,47 @@
 import p5 from 'p5';
 /**
- * Global singleton context for the Brick Engine.
- * Provides read-only access to the p5 instance across the application.
+ * Global singleton context responsible for exposing the rendering engine instance.
+ *
+ * Designed to decouple the rendering logic from the core game state and input
+ * processing. By providing a centralized, read-only access point to the `p5`
+ * instance, it eliminates the need to pass the `p5` object via dependency
+ * injection down to every component, view, and layout throughout the architecture.
  */
 export default class RendererContext {
     private static _p;
     /**
-     * Initializes the RendererContext with a p5 instance.
-     * Should only be called once, typically during Game initialization.
-     * @param pInstance The active p5 instance.
-     * @throws Error if the context has already been initialized.
+     * Initializes the global renderer context with the active p5 instance.
+     *
+     * This method is designed to be called exactly once during the application
+     * startup lifecycle, typically by the engine's entry point. It stores the
+     * `p5` object internally. If called multiple times, it safely ignores subsequent
+     * calls and emits a console warning to prevent accidental overwrites of the
+     * core rendering capabilities.
+     *
+     * @param {p5} pInstance - The active, initialized `p5` instance that will be shared across the application.
+     * @returns {void} Returns nothing.
      */
     static init(pInstance: p5): void;
     /**
-     * Gets the globally available p5 instance.
-     * @throws Error if the context has not been initialized yet.
+     * Retrieves the globally available p5 instance.
+     *
+     * Acts as the primary access point for any drawing or rendering operation across
+     * the application ecosystem. UI Components and Renderers should access `p` from
+     * this context to perform canvas updates safely.
+     *
+     * @throws {Error} Thrown if this getter is accessed before the `init` method has been successfully executed, preventing silent failures during render cycles.
+     * @returns {p5} The active, initialized `p5` instance.
      */
     static get p(): p5;
     /**
-     * Resets the context.
-     * Primarily used for unit testing to clear the singleton state.
+     * Resets the safely stored global p5 context.
+     *
+     * Used strictly to support test isolation. It clears the singleton state
+     * internally to ensure that unit tests utilizing virtual `p5` mock instances
+     * can be created and torn down reliably across test suites without retaining
+     * state from previous executions.
+     *
+     * @returns {void} Returns nothing.
      */
     static reset(): void;
 }

package/dist/types/core/event/EventEmitter.d.ts

@@ -1,6 +1,10 @@
 type EventCallback<T = any> = (payload?: T) => void;
 /**
  * Narrow interface representing the engine state context required for contextual notifications.
+ *
+ * Designed to decouple the {@link EventEmitter} from the full `GameState` module.
+ * It allows the emitter to query specific state properties without creating
+ * circular dependencies, enabling dynamic routing of events into state-specific channels.
  */
 export interface StateContext {
     isPlaying(): boolean;
@@ -11,6 +15,10 @@ export interface StateContext {
 }
 /**
  * Valid event suffixes for contextual dispatch.
+ *
+ * Defines the strict set of string identifiers appended to base events to
+ * create state-specific subscription channels. This guarantees type safety
+ * when modules choose to listen only during specific game lifecycles.
  */
 export declare enum EventSuffix {
     TITLE = "title",
@@ -20,51 +28,86 @@ export declare enum EventSuffix {
 }
 /**
  * Static event emitter for global pub/sub communication across the engine.
+ *
+ * Acts as the centralized communication backbone of the engine reactor,
+ * allowing entirely decoupled modules to hook into each other's lifecycles.
+ * By preventing tight coupling and direct method calls, it enables highly
+ * scalable logic flow where input events or state changes can be broadcasted
+ * to any interested subsystem dynamically.
  */
 export default class EventEmitter {
     private static _events;
     /**
-     * Subscribes to an event.
+     * Subscribes a listener callback to an event channel.
      *
-     * @param eventName The name of the event to listen for.
-     * @param callback The function to execute when the event is emitted.
-     * @param suffix The optional context suffix.
+     * Registers a callback function to be executed whenever the specified event
+     * is emitted. If a {@link EventSuffix} is provided, it subscribes to the
+     * contextual sub-channel (e.g. `UP:playing`) instead of the base channel.
+     *
+     * @param {string} eventName - The base string identifier of the event to listen for.
+     * @param {EventCallback<T>} callback - The function to execute when the event triggers. Receives the payload if applicable.
+     * @param {EventSuffix} [suffix] - The optional modifier to listen only on state-restricted channels.
+     * @returns {void} Returns nothing.
      */
     static subscribe<T>(eventName: string, callback: EventCallback<T>, suffix?: EventSuffix): void;
     /**
-     * Unsubscribes from an event.
+     * Unsubscribes an existing listener from an event channel.
+     *
+     * Safely removes the provided callback from the notification queue.
+     * If the event was subscribed with a suffix, the same {@link EventSuffix}
+     * must be provided here to target the correct sub-channel.
      *
-     * @param eventName The name of the event.
-     * @param callback The specific callback function to remove.
-     * @param suffix The optional context suffix.
+     * @param {string} eventName - The base string identifier of the event.
+     * @param {EventCallback<T>} callback - The exact function reference previously passed to `subscribe`.
+     * @param {EventSuffix} [suffix] - The optional context restricted modifier previously utilized.
+     * @returns {void} Returns nothing.
      */
     static unsubscribe<T>(eventName: string, callback: EventCallback<T>, suffix?: EventSuffix): void;
     /**
-     * Emits an event, triggering all registered callbacks with the provided payload.
+     * Emits a standard event, triggering all registered standard callbacks.
      *
-     * @param eventName The name of the event to emit.
-     * @param payload Optional data to pass to the callbacks.
+     * Iterates over all callbacks associated with the given channel key and
+     * invokes them sequentially with the provided payload. This acts strictly
+     * on the base channel without evaluating current game states.
+     *
+     * @param {string} eventName - The precise name of the channel to broadcast on.
+     * @param {T} [payload] - The optional contextual data payload passed structurally to each callback.
+     * @returns {void} Returns nothing.
      */
     static notify<T>(eventName: string, payload?: T): void;
     /**
-     * Dispatches an event to the base channel and automatically to contextual channels
-     * (:playing, :title, :gameover, :paused) based on the provided state context.
+     * Dispatches an event to the base channel and evaluates contextual channels.
+     *
+     * Performs a standard notify on the base `eventName`, and then evaluates
+     * the provided {@link StateContext} to decide which secondary {@link EventSuffix}
+     * channel should also receive the payload. This enables multi-cast
+     * signals where listeners can opt into receiving only under certain states.
      *
-     * @param eventName The base name of the event.
-     * @param payload Optional data to pass to the callbacks.
-     * @param context The engine state context.
+     * @param {string} eventName - The core string identifier of the event broadcast.
+     * @param {T} payload - The required event data to be passed to callbacks in both base and context channels.
+     * @param {StateContext} context - The engine state provider used to determine applicable conditions (Playing, Paused, Title, Gameover).
+     * @returns {void} Returns nothing.
      */
     static notifyContextual<T>(eventName: string, payload: T, context: StateContext): void;
     /**
-     * Formats an event name with an optional suffix.
+     * Formats an event name with an optional localized suffix string.
      *
-     * @param base The base event name.
-     * @param suffix The optional context suffix.
-     * @returns The formatted event string.
+     * Used internally to guarantee uniform string keys when registering or
+     * triggering targeted contextual communication channels.
+     *
+     * @param {string} base - The fundamental event identifier string.
+     * @param {EventSuffix} [suffix] - The specific contextual modifier enum to append.
+     * @returns {string} The fully combined and formatted channel key suitable for indexing the internal registry.
      */
     private static _formatName;
     /**
-     * Clears all registered events and listeners. Useful for cleanup or testing.
+     * Clears all universally registered events and listener channels.
+     *
+     * Highly destructive, this function wipes the entire internal communications
+     * map. Primarily purposed for unit testing workflows to ensure zero listener
+     * contamination across differing test cases.
+     *
+     * @returns {void} Returns nothing.
      */
     static clear(): void;
 }

package/dist/types/core/event/GameEventRegistry.d.ts

@@ -1,20 +1,34 @@
 import { GameModules } from '../types/Types';
 /**
  * Registry for system-level game events.
+ *
  * Centralizes the logic for power, reset, and state-based notifications.
+ * By moving these registrations out of the core Game class, it maintains
+ * a clean startup sequence and ensures that all modules remain decoupled
+ * while still reacting to global lifecycle changes like turning on/off or Game Over.
  */
 export default class GameEventRegistry {
     /**
      * Sets up all system-level control event subscriptions.
      *
-     * @param modules - The collection of game modules.
-     * @param onReset - Callback to restore the initial state of the game instance.
+     * Injects handlers for core game hardware button mappings like power cycling,
+     * resetting the active game, unpausing, or modifying hardware toggles like
+     * sound and color.
+     *
+     * @param {GameModules} modules - The collection of initialized game modules to bind.
+     * @param {() => void} onReset - Callback to be executed immediately to restore the initial properties of the game instance during soft resets.
+     * @returns {void} Returns nothing.
      */
     static setupControlEvents(modules: GameModules, onReset: () => void): void;
     /**
      * Sets up all system-level state property subscriptions.
      *
-     * @param modules - The collection of game modules.
+     * Binds lifecycle behaviors to state property changes, such as clearing
+     * current session data upon encountering Game Over, or fully purging
+     * rendering/grid variables when the system is virtually powered down.
+     *
+     * @param {GameModules} modules - The structured collection of engine modules.
+     * @returns {void} Returns nothing.
      */
     static setupStateEvents(modules: GameModules): void;
 }

package/dist/types/core/helpers/CellHelper.d.ts

@@ -1,13 +1,20 @@
 import { Cell, Coordinate } from '../types/Types';
 /**
- * Utility class for creating and managing grid cells.
+ * Static factory utility class for creating and initializing Cell objects.
+ *
+ * Provides a reliable and centralized mechanism to instantiate default grid
+ * cells. This ensures that every cell generated across the engine instances
+ * starts with identical baseline properties, preventing inconsistent state setup.
  */
 export default class CellHelper {
     /**
-     * Creates a new empty cell at the specified coordinate.
+     * Creates a new empty cell structure at the specified coordinate.
      *
-     * @param {Coordinate} coordinate - The location of the new cell.
-     * @returns {Cell} A new cell object initialized with value 0 and default color.
+     * Constructs a baseline entity used primarily by the `GameGrid` to populate
+     * its internal matrix during allocation or when a row/column is cleared.
+     *
+     * @param {Coordinate} coordinate - The precise `{x, y}` grid location to assign to the new cell.
+     * @returns {Cell} A new cell object strictly initialized with a `value` of 0 and the `Color.DEFAULT` assignment.
      */
     static emptyCell(coordinate: Coordinate): Cell;
 }

package/dist/types/core/helpers/ControlInputHandlerHelper.d.ts

@@ -1,32 +1,41 @@
 import { ControlKey } from '../types/Types';
 import { Control } from '../types/modules';
 /**
- * Helper class that standardizes input handling logic.
- * It manages the distinction between single 'press' events and continuous 'hold' events
- * for both keyboard and UI button inputs.
+ * Utility responsible for standardizing input lifecycle and event dispatching.
+ *
+ * Normalizes raw hardware keyboard events or UI button clicks into abstract
+ * {@link ControlKey} actions. It handles the complexity of identifying the
+ * nuance between a quick "press" and a sustained "hold", offloading this
+ * timer logic from the core {@link GameControl} module.
  */
 export default class ControlInputHandlerHelper {
     private _control;
     private _activeKeys;
     /**
-     * Creates an instance of the input handler.
+     * Instantiates an active input loop handler context.
      *
-     * @param {Control} control - The control module instance to notify.
+     * @param {Control} control - The parent control module instance used to notify normalized events.
      */
     constructor(control: Control);
     /**
-     * Processes a key down or button press action.
+     * Processes a new physical key down or virtual button press interaction.
+     *
      * Triggers an immediate {@link ControlEventType.PRESSED} event, and schedules
-     * a {@link ControlEventType.HELD} loop if the key remains active.
+     * a continuous {@link ControlEventType.HELD} loop interval if the key remains
+     * actively depressed past the configuration threshold.
      *
-     * @param {ControlKey} key - The identity of the control key being pressed.
+     * @param {ControlKey} key - The identity of the abstract control key being activated.
+     * @returns {void} Returns nothing.
      */
     handlePress(key: ControlKey): void;
     /**
-     * Processes a key up or button release action.
-     * Cancels any pending hold timers and cleans up the active key state.
+     * Stops tracking an active key interaction upon physical or virtual release.
+     *
+     * Cancels any pending hold delay timers and cleanly wipes the active key
+     * state from memory to stop {@link ControlEventType.HELD} events from firing.
      *
-     * @param {ControlKey} key - The identity of the control key being released.
+     * @param {ControlKey} key - The identity of the abstract control key being released.
+     * @returns {void} Returns nothing.
      */
     handleRelease(key: ControlKey): void;
 }

package/dist/types/core/helpers/CoordinateHelper.d.ts

@@ -1,48 +1,53 @@
 import { Coordinate } from '../types/Types';
 /**
- * Static utility class for coordinate transformations.
- * Handles conversions between relative (0-1) coordinates and absolute pixel positions
- * for both the main display and the HUD.
+ * Static mathematical utility class for coordinate transformations and translations.
+ *
+ * Centralizes the logic to transition between abstract engine logical models (e.g.
+ * the relative 0.0-1.0 coordinate plane or abstract {@link GameGrid} spaces) and
+ * the absolute physical layout on screen. It ensures consistency in calculating
+ * element sizes dynamically, keeping UI layouts natively responsive to canvas bounds.
  */
 export default class CoordinateHelper {
     /**
-     * Converts a simplified coordinate object to relative screen dimensions.
+     * Converts a flat abstract coordinate object into relative screen dimensional scaling.
      *
-     * @param {Coordinate} coordinate - The normal coordinate.
-     * @returns {Coordinate} A new coordinate scaled to the canvas width/height.
+     * @param {Coordinate} coordinate - The input logical coordinate structure (x, y).
+     * @returns {Coordinate} A new coordinate scaled proportionately to the physical base canvas width/height.
      */
     static getRelativeCoordinate(coordinate: Coordinate): Coordinate;
     /**
-     * Calculates the absolute X pixel position for an element on the Main Display.
+     * Calculates the absolute `X` pixel position for an element rendered on the Main Display.
      *
-     * @param {number} x - The relative or normalized X position.
-     * @param {number} displayWidth - The calculated width of the display area.
-     * @returns {number} The absolute X pixel coordinate.
+     * @param {number} x - The relative or normalized input X horizontal position.
+     * @param {number} displayWidth - The dynamically calculated width of the central display area.
+     * @returns {number} The absolute horizontal offset pixel coordinate formatted for `p5` rendering functions.
      */
     static getDisplayPosX(x: number, displayWidth: number): number;
     /**
-     * Calculates the absolute Y pixel position for an element on the Main Display.
+     * Calculates the absolute `Y` pixel position for an element rendered on the Main Display.
      *
-     * @param {number} y - The relative or normalized Y position.
-     * @param {number} displayHeight - The calculated height of the display area.
-     * @returns {number} The absolute Y pixel coordinate.
+     * @param {number} y - The relative or normalized input Y vertical position.
+     * @param {number} displayHeight - The dynamically calculated height of the central display area.
+     * @returns {number} The absolute vertical offset pixel coordinate formatted for `p5` rendering functions.
      */
     static getDisplayPosY(y: number, displayHeight: number): number;
     /**
-     * Calculates the absolute X pixel position for an element on the HUD.
-     * Use this to position elements in the sidebar.
+     * Calculates the absolute `X` pixel position for an element docked to the right-side HUD column.
      *
-     * @param {number} x - The relative or normalized X position within the HUD.
-     * @param {number} displayWidth - The width of the main display (used for offset calculation).
-     * @returns {number} The absolute X pixel coordinate.
+     * Automatically adjusts its starting position by determining where the
+     * Main Display ends physically, injecting proper UI margin limits dynamically.
+     *
+     * @param {number} x - The relative or normalized X position specifically within the bounded HUD compartment.
+     * @param {number} displayWidth - The total real width of the central display (used for zero-point alignment calculation).
+     * @returns {number} The absolute X horizontal pixel coordinate within the application layout scale.
      */
     static getHudPosX(x: number, displayWidth: number): number;
     /**
-     * Calculates the absolute Y pixel position for an element on the HUD.
+     * Calculates the absolute `Y` pixel position for an element docked to the right-side HUD column.
      *
-     * @param {number} y - The relative or normalized Y position within the HUD.
-     * @param {number} displayHeight - The height of the main display (used for scaling).
-     * @returns {number} The absolute Y pixel coordinate.
+     * @param {number} y - The relative or normalized Y position specifically within the bounded HUD compartment.
+     * @param {number} displayHeight - The absolute pixel height assigned logically to the central display (used for scaled positioning bounds).
+     * @returns {number} The absolute Y vertical pixel coordinate within the application layout scale.
      */
     static getHudPosY(y: number, displayHeight: number): number;
 }