@arcane-engine/runtime 0.1.0 → 0.2.0

package/src/pathfinding/types.ts

@@ -1,21 +1,60 @@
 import type { Vec2 } from "../state/types.ts";
 
+/**
+ * A grid abstraction for pathfinding.
+ *
+ * Provides dimensions and callbacks for walkability and movement cost.
+ * Tiles are addressed by integer (x, y) coordinates where (0,0) is the top-left.
+ */
 export type PathGrid = {
+  /** Grid width in tiles. Must be > 0. */
   width: number;
+  /** Grid height in tiles. Must be > 0. */
   height: number;
+  /**
+   * Returns whether the tile at (x, y) can be traversed.
+   * @param x - Tile X coordinate, 0..width-1.
+   * @param y - Tile Y coordinate, 0..height-1.
+   * @returns True if the tile is walkable.
+   */
   isWalkable: (x: number, y: number) => boolean;
+  /**
+   * Optional movement cost for entering the tile at (x, y).
+   * If omitted, cardinal moves cost 1 and diagonal moves cost sqrt(2).
+   * @param x - Tile X coordinate.
+   * @param y - Tile Y coordinate.
+   * @returns Movement cost. Must be > 0. Higher values = harder to traverse.
+   */
   cost?: (x: number, y: number) => number;
 };
 
+/**
+ * Options for {@link findPath}.
+ */
 export type PathOptions = {
+  /** Allow diagonal movement (8-directional). Default: false (4-directional). */
   diagonal?: boolean;
+  /** Maximum A* iterations before giving up. Default: 10000. Prevents runaway on large grids. */
   maxIterations?: number;
+  /**
+   * Heuristic function for distance estimation.
+   * - `"manhattan"` — sum of axis distances. Best for 4-directional movement. (Default)
+   * - `"euclidean"` — straight-line distance. Best for any-angle movement.
+   * - `"chebyshev"` — max of axis distances. Best for 8-directional movement.
+   */
   heuristic?: "manhattan" | "euclidean" | "chebyshev";
 };
 
+/**
+ * Result returned by {@link findPath}.
+ */
 export type PathResult = {
+  /** Whether a path from start to goal was found. */
   found: boolean;
+  /** Ordered array of tile positions from start to goal (inclusive). Empty if not found. */
   path: Vec2[];
+  /** Total movement cost of the path. 0 if not found. */
   cost: number;
+  /** Number of tiles explored during the search. Useful for profiling. */
   explored: number;
 };

package/src/physics/aabb.ts

@@ -1,18 +1,51 @@
-/** Axis-Aligned Bounding Box */
+/**
+ * Axis-Aligned Bounding Box for 2D collision detection.
+ * Defined by its top-left corner and dimensions.
+ *
+ * - `x` - Left edge position (world units).
+ * - `y` - Top edge position (world units).
+ * - `w` - Width. Must be >= 0.
+ * - `h` - Height. Must be >= 0.
+ */
 export type AABB = {
-  x: number;  // left edge
-  y: number;  // top edge
-  w: number;  // width
-  h: number;  // height
+  x: number;
+  y: number;
+  w: number;
+  h: number;
 };
 
-/** Check if two AABBs overlap */
+/**
+ * Check if two AABBs overlap. Pure function.
+ * Uses the separating axis theorem — returns true if there is no gap between
+ * the boxes on either the X or Y axis.
+ *
+ * @param a - First bounding box.
+ * @param b - Second bounding box.
+ * @returns True if the boxes overlap (touching edges do not count as overlap).
+ *
+ * @example
+ * const player = { x: 10, y: 10, w: 16, h: 16 };
+ * const enemy = { x: 20, y: 10, w: 16, h: 16 };
+ * if (aabbOverlap(player, enemy)) {
+ *   // Handle collision
+ * }
+ */
 export function aabbOverlap(a: AABB, b: AABB): boolean {
   return a.x < b.x + b.w && a.x + a.w > b.x &&
          a.y < b.y + b.h && a.y + a.h > b.y;
 }
 
-/** Check if a circle overlaps an AABB */
+/**
+ * Check if a circle overlaps an AABB. Pure function.
+ * Finds the closest point on the AABB to the circle center
+ * and checks if it's within the radius.
+ *
+ * @param cx - Circle center X position.
+ * @param cy - Circle center Y position.
+ * @param radius - Circle radius. Must be >= 0.
+ * @param box - The AABB to test against.
+ * @returns True if the circle and AABB overlap (inclusive of touching).
+ */
 export function circleAABBOverlap(
   cx: number, cy: number, radius: number,
   box: AABB
@@ -24,7 +57,21 @@ export function circleAABBOverlap(
   return (dx * dx + dy * dy) <= (radius * radius);
 }
 
-/** Get collision normal for circle vs AABB. Returns null if no collision. */
+/**
+ * Get the collision resolution normal for a circle vs AABB collision.
+ * Returns a unit normal vector pointing from the AABB toward the circle center,
+ * or null if there is no collision.
+ *
+ * When the circle center is inside the AABB, pushes out along the shortest axis
+ * relative to the box center.
+ *
+ * @param cx - Circle center X position.
+ * @param cy - Circle center Y position.
+ * @param radius - Circle radius. Must be >= 0.
+ * @param box - The AABB to resolve against.
+ * @returns Object with `nx` and `ny` (unit normal), or null if no collision.
+ *          nx and ny are in the range [-1, 1] and form a unit vector.
+ */
 export function circleAABBResolve(
   cx: number, cy: number, radius: number,
   box: AABB

package/src/rendering/animation.ts

@@ -1,27 +1,55 @@
 import type { TextureId } from "./types.ts";
 import { drawSprite } from "./sprites.ts";
 
+/**
+ * Opaque handle to a registered animation definition.
+ * Returned by {@link createAnimation}.
+ */
 export type AnimationId = number;
 
+/** Internal definition of a sprite-sheet animation. */
 export type AnimationDef = {
+  /** Texture handle containing the sprite sheet. */
   textureId: TextureId;
+  /** Width of each animation frame in pixels. */
   frameW: number;
+  /** Height of each animation frame in pixels. */
   frameH: number;
+  /** Total number of frames in the animation. */
   frameCount: number;
+  /** Playback speed in frames per second. */
   fps: number;
+  /** If true, animation loops. If false, stops on last frame. */
   loop: boolean;
 };
 
+/** State of a playing animation instance. Immutable -- update via {@link updateAnimation}. */
 export type AnimationState = {
+  /** Reference to the animation definition. */
   defId: AnimationId;
+  /** Total elapsed time in seconds since animation started. */
   elapsed: number;
+  /** Current frame index (0-based). */
   frame: number;
+  /** True if non-looping animation has reached its last frame. */
   finished: boolean;
 };
 
 const registry = new Map<number, AnimationDef>();
 let nextId = 1;
 
+/**
+ * Register a sprite-sheet animation definition.
+ * Frames must be arranged in a single horizontal row in the texture.
+ *
+ * @param textureId - Texture handle of the sprite sheet (from loadTexture()).
+ * @param frameW - Width of each frame in pixels.
+ * @param frameH - Height of each frame in pixels.
+ * @param frameCount - Number of frames in the animation.
+ * @param fps - Playback speed in frames per second. Higher = faster.
+ * @param options - Optional settings. `loop`: whether to loop (default: true).
+ * @returns AnimationId handle for use with playAnimation().
+ */
 export function createAnimation(
   textureId: TextureId,
   frameW: number,
@@ -42,10 +70,24 @@ export function createAnimation(
   return id;
 }
 
+/**
+ * Create a new animation playback state starting from frame 0.
+ *
+ * @param defId - AnimationId from createAnimation().
+ * @returns Fresh AnimationState at frame 0.
+ */
 export function playAnimation(defId: AnimationId): AnimationState {
   return { defId, elapsed: 0, frame: 0, finished: false };
 }
 
+/**
+ * Advance an animation by a time delta. Returns a new immutable state.
+ * For looping animations, wraps around. For non-looping, stops at the last frame.
+ *
+ * @param anim - Current animation state.
+ * @param dt - Time delta in seconds (from getDeltaTime()).
+ * @returns Updated animation state.
+ */
 export function updateAnimation(
   anim: AnimationState,
   dt: number,
@@ -83,6 +125,13 @@ export function updateAnimation(
   };
 }
 
+/**
+ * Get the UV sub-rectangle for the current animation frame.
+ * Used internally by drawAnimatedSprite; also useful for custom rendering.
+ *
+ * @param anim - Current animation state.
+ * @returns UV rect (0.0-1.0 normalized) for the current frame.
+ */
 export function getAnimationUV(
   anim: AnimationState,
 ): { x: number; y: number; w: number; h: number } {
@@ -97,6 +146,18 @@ export function getAnimationUV(
   };
 }
 
+/**
+ * Draw an animated sprite at the given position using the current animation frame.
+ * Combines getAnimationUV() + drawSprite() for convenience.
+ * Must be called every frame. No-op if the animation definition is not found.
+ *
+ * @param anim - Current animation state (from playAnimation/updateAnimation).
+ * @param x - World X position (top-left corner).
+ * @param y - World Y position (top-left corner).
+ * @param w - Width in world units.
+ * @param h - Height in world units.
+ * @param options - Optional layer and tint overrides.
+ */
 export function drawAnimatedSprite(
   anim: AnimationState,
   x: number,
@@ -123,10 +184,22 @@ export function drawAnimatedSprite(
   });
 }
 
+/**
+ * Reset an animation to frame 0 (restart from beginning).
+ *
+ * @param anim - Animation state to reset.
+ * @returns New animation state at frame 0, not finished.
+ */
 export function resetAnimation(anim: AnimationState): AnimationState {
   return { ...anim, elapsed: 0, frame: 0, finished: false };
 }
 
+/**
+ * Stop an animation immediately by marking it as finished.
+ *
+ * @param anim - Animation state to stop.
+ * @returns New animation state with finished = true.
+ */
 export function stopAnimation(anim: AnimationState): AnimationState {
   return { ...anim, finished: true };
 }

package/src/rendering/audio.ts

@@ -1,8 +1,14 @@
-/** Opaque handle to a loaded sound. */
+/**
+ * Opaque handle to a loaded sound. Returned by {@link loadSound}.
+ * A value of 0 means "no sound" (headless mode fallback).
+ */
 export type SoundId = number;
 
+/** Options for {@link playSound}. */
 export type PlayOptions = {
+  /** Playback volume, 0.0 (silent) to 1.0 (full). Default: 1.0. */
   volume?: number;
+  /** If true, sound loops until stopped. Default: false. */
   loop?: boolean;
 };
 
@@ -11,9 +17,12 @@ const hasRenderOps =
   typeof (globalThis as any).Deno?.core?.ops?.op_load_sound === "function";
 
 /**
- * Load a sound file (WAV, OGG, MP3). Returns a sound handle.
- * Caches by path — loading the same path twice returns the same handle.
+ * Load a sound file (WAV, OGG, MP3). Returns an opaque sound handle.
+ * Caches by path -- loading the same path twice returns the same handle.
  * Returns 0 in headless mode.
+ *
+ * @param path - File path to an audio file (relative to game entry file or absolute).
+ * @returns Sound handle for use with playSound(), stopSound().
  */
 export function loadSound(path: string): SoundId {
   if (!hasRenderOps) return 0;
@@ -21,8 +30,11 @@ export function loadSound(path: string): SoundId {
 }
 
 /**
- * Play a loaded sound.
+ * Play a loaded sound effect.
  * No-op in headless mode.
+ *
+ * @param id - Sound handle from loadSound().
+ * @param options - Volume and loop settings.
  */
 export function playSound(id: SoundId, options?: PlayOptions): void {
   if (!hasRenderOps) return;
@@ -32,9 +44,13 @@ export function playSound(id: SoundId, options?: PlayOptions): void {
 }
 
 /**
- * Convenience: load and play a sound file as looping music.
- * Returns the sound ID for later stopping.
+ * Load and play a sound file as looping background music.
+ * Convenience function combining loadSound() + playSound() with loop: true.
  * Returns 0 in headless mode.
+ *
+ * @param path - File path to an audio file.
+ * @param volume - Playback volume, 0.0-1.0. Default: 1.0.
+ * @returns Sound handle for later stopping with stopSound().
  */
 export function playMusic(path: string, volume: number = 1.0): SoundId {
   const id = loadSound(path);
@@ -43,8 +59,10 @@ export function playMusic(path: string, volume: number = 1.0): SoundId {
 }
 
 /**
- * Stop a specific sound.
+ * Stop a specific playing sound.
  * No-op in headless mode.
+ *
+ * @param id - Sound handle from loadSound() or playMusic().
  */
 export function stopSound(id: SoundId): void {
   if (!hasRenderOps) return;
@@ -52,7 +70,7 @@ export function stopSound(id: SoundId): void {
 }
 
 /**
- * Stop all playing sounds.
+ * Stop all currently playing sounds and music.
  * No-op in headless mode.
  */
 export function stopAll(): void {
@@ -61,8 +79,10 @@ export function stopAll(): void {
 }
 
 /**
- * Set the master volume (0.0 = mute, 1.0 = full).
+ * Set the master volume for all audio output.
  * No-op in headless mode.
+ *
+ * @param volume - Master volume level, 0.0 (mute) to 1.0 (full). Values outside this range are not clamped.
  */
 export function setVolume(volume: number): void {
   if (!hasRenderOps) return;

package/src/rendering/camera.ts

@@ -5,8 +5,21 @@ const hasRenderOps =
   typeof (globalThis as any).Deno?.core?.ops?.op_set_camera === "function";
 
 /**
- * Set the camera position and zoom.
+ * Set the camera position and zoom level.
+ * The camera determines which part of the world is visible on screen.
  * No-op in headless mode.
+ *
+ * @param x - Camera center X in world units.
+ * @param y - Camera center Y in world units.
+ * @param zoom - Zoom level. 1.0 = default, >1.0 = zoomed in, <1.0 = zoomed out. Default: 1.
+ *
+ * @example
+ * // Center camera on the player
+ * setCamera(player.x, player.y);
+ *
+ * @example
+ * // Zoomed-in camera
+ * setCamera(player.x, player.y, 2.0);
  */
 export function setCamera(x: number, y: number, zoom: number = 1): void {
   if (!hasRenderOps) return;
@@ -14,8 +27,10 @@ export function setCamera(x: number, y: number, zoom: number = 1): void {
 }
 
 /**
- * Get the current camera state.
- * Returns default values in headless mode.
+ * Get the current camera state (position and zoom).
+ * Returns `{ x: 0, y: 0, zoom: 1 }` in headless mode.
+ *
+ * @returns Current camera position and zoom level.
  */
 export function getCamera(): CameraState {
   if (!hasRenderOps) return { x: 0, y: 0, zoom: 1 };
@@ -24,7 +39,16 @@ export function getCamera(): CameraState {
 }
 
 /**
- * Center the camera on a target position.
+ * Center the camera on a target position. Convenience wrapper around {@link setCamera}.
+ * Call every frame to follow a moving target.
+ *
+ * @param targetX - Target X position in world units to center on.
+ * @param targetY - Target Y position in world units to center on.
+ * @param zoom - Zoom level. Default: 1.
+ *
+ * @example
+ * // Follow the player each frame
+ * followTarget(player.x, player.y);
  */
 export function followTarget(
   targetX: number,

package/src/rendering/input.ts

@@ -10,9 +10,25 @@ const hasViewportOp =
   typeof (globalThis as any).Deno?.core?.ops?.op_get_viewport_size === "function";
 
 /**
- * Check if a key is currently held down.
- * Key names match web standards: "ArrowUp", "ArrowDown", "a", "Space", etc.
+ * Check if a key is currently held down (returns true every frame while held).
  * Returns false in headless mode.
+ *
+ * Key names follow web KeyboardEvent.key standards:
+ * - Arrow keys: `"ArrowUp"`, `"ArrowDown"`, `"ArrowLeft"`, `"ArrowRight"`
+ * - Letters: `"a"` - `"z"` (lowercase)
+ * - Digits: `"0"` - `"9"`
+ * - Function keys: `"F1"` - `"F12"`
+ * - Whitespace: `"Space"`, `"Tab"`, `"Enter"`
+ * - Modifiers: `"Shift"`, `"Control"`, `"Alt"`
+ * - Navigation: `"Escape"`, `"Backspace"`, `"Delete"`, `"Home"`, `"End"`, `"PageUp"`, `"PageDown"`
+ *
+ * @param key - Key name string (case-sensitive, web standard).
+ * @returns true if the key is currently held down, false otherwise.
+ *
+ * @example
+ * if (isKeyDown("ArrowRight")) {
+ *   player.x += speed * dt;
+ * }
  */
 export function isKeyDown(key: string): boolean {
   if (!hasRenderOps) return false;
@@ -20,8 +36,17 @@ export function isKeyDown(key: string): boolean {
 }
 
 /**
- * Check if a key was pressed this frame (just went down).
+ * Check if a key was pressed this frame (transitioned from up to down).
+ * Unlike {@link isKeyDown}, this returns true only on the first frame the key is pressed.
  * Returns false in headless mode.
+ *
+ * Valid key names are the same as {@link isKeyDown}:
+ * `"ArrowUp"`, `"ArrowDown"`, `"ArrowLeft"`, `"ArrowRight"`, `"Space"`, `"Enter"`,
+ * `"Escape"`, `"Tab"`, `"Shift"`, `"Control"`, `"Alt"`, `"a"`-`"z"`, `"0"`-`"9"`, `"F1"`-`"F12"`,
+ * `"Backspace"`, `"Delete"`, `"Home"`, `"End"`, `"PageUp"`, `"PageDown"`.
+ *
+ * @param key - Key name string (case-sensitive, web standard).
+ * @returns true if the key was just pressed this frame, false otherwise.
  */
 export function isKeyPressed(key: string): boolean {
   if (!hasRenderOps) return false;
@@ -29,8 +54,12 @@ export function isKeyPressed(key: string): boolean {
 }
 
 /**
- * Get the current mouse position in window/screen coordinates.
- * Returns (0, 0) in headless mode.
+ * Get the current mouse position in screen/window coordinates (pixels).
+ * (0, 0) is the top-left corner of the window.
+ * Returns `{ x: 0, y: 0 }` in headless mode.
+ * Use {@link getMouseWorldPosition} for world-space coordinates.
+ *
+ * @returns Mouse position in screen pixels.
  */
 export function getMousePosition(): MousePosition {
   if (!hasRenderOps) return { x: 0, y: 0 };
@@ -40,7 +69,9 @@ export function getMousePosition(): MousePosition {
 
 /**
  * Get the current viewport size in pixels.
- * Returns [800, 600] in headless mode.
+ * Returns `{ width: 800, height: 600 }` in headless mode.
+ *
+ * @returns Viewport dimensions in pixels.
  */
 export function getViewportSize(): { width: number; height: number } {
   if (!hasViewportOp) return { width: 800, height: 600 };
@@ -50,8 +81,11 @@ export function getViewportSize(): { width: number; height: number } {
 
 /**
  * Convert screen/window coordinates to world coordinates using the current camera.
- * Screen coordinates: (0, 0) = top-left, (viewport_width, viewport_height) = bottom-right
- * World coordinates: transformed by camera position and zoom
+ * Accounts for camera position and zoom.
+ *
+ * @param screenX - X position in screen pixels (0 = left edge).
+ * @param screenY - Y position in screen pixels (0 = top edge).
+ * @returns Corresponding world-space position.
  */
 export function screenToWorld(screenX: number, screenY: number): MousePosition {
   const viewport = getViewportSize();
@@ -74,7 +108,9 @@ export function screenToWorld(screenX: number, screenY: number): MousePosition {
 
 /**
  * Get the mouse position in world coordinates (accounting for camera transform).
- * This is a convenience function that combines getMousePosition() and screenToWorld().
+ * Convenience function combining {@link getMousePosition} and {@link screenToWorld}.
+ *
+ * @returns Mouse position in world units.
  */
 export function getMouseWorldPosition(): MousePosition {
   const screenPos = getMousePosition();

package/src/rendering/lighting.ts

@@ -3,13 +3,35 @@ const hasRenderOps =
   typeof (globalThis as any).Deno?.core?.ops?.op_set_ambient_light ===
     "function";
 
-/** Set the ambient light color (0-1 per channel). Default is (1,1,1) = full white. */
+/**
+ * Set the ambient light color applied to all sprites.
+ * (1, 1, 1) = full white (no darkening, the default).
+ * (0, 0, 0) = complete darkness (only point lights visible).
+ * No-op in headless mode.
+ *
+ * @param r - Red channel, 0.0-1.0.
+ * @param g - Green channel, 0.0-1.0.
+ * @param b - Blue channel, 0.0-1.0.
+ */
 export function setAmbientLight(r: number, g: number, b: number): void {
   if (!hasRenderOps) return;
   (globalThis as any).Deno.core.ops.op_set_ambient_light(r, g, b);
 }
 
-/** Add a point light at world position (x,y) with the given radius, color, and intensity. */
+/**
+ * Add a point light at a world position.
+ * Point lights illuminate sprites within their radius, blending with the ambient light.
+ * Must be called every frame (lights are cleared at frame start).
+ * No-op in headless mode.
+ *
+ * @param x - Light center X in world units.
+ * @param y - Light center Y in world units.
+ * @param radius - Light radius in world units. Falloff is smooth to the edge.
+ * @param r - Light color red channel, 0.0-1.0. Default: 1.
+ * @param g - Light color green channel, 0.0-1.0. Default: 1.
+ * @param b - Light color blue channel, 0.0-1.0. Default: 1.
+ * @param intensity - Light brightness multiplier, 0.0+. Default: 1.
+ */
 export function addPointLight(
   x: number,
   y: number,
@@ -31,7 +53,11 @@ export function addPointLight(
   );
 }
 
-/** Clear all point lights for this frame. Called automatically at frame start. */
+/**
+ * Clear all point lights for this frame.
+ * Called automatically at frame start by the renderer; manual use is rarely needed.
+ * No-op in headless mode.
+ */
 export function clearLights(): void {
   if (!hasRenderOps) return;
   (globalThis as any).Deno.core.ops.op_clear_lights();

package/src/rendering/loop.ts

@@ -3,9 +3,19 @@ const hasRenderOps =
   typeof (globalThis as any).Deno?.core?.ops?.op_get_delta_time === "function";
 
 /**
- * Register a callback to be called each frame.
- * Only one callback can be active at a time (last one wins).
- * No-op in headless mode.
+ * Register a callback to be called every frame by the Arcane renderer.
+ * Only one callback can be active -- calling onFrame() again replaces the previous one.
+ * The callback is invoked by the Rust game loop (not by requestAnimationFrame).
+ * No-op in headless mode (the callback is stored but never invoked).
+ *
+ * @param callback - Function to call each frame. Use {@link getDeltaTime} inside for timing.
+ *
+ * @example
+ * onFrame(() => {
+ *   const dt = getDeltaTime();
+ *   player.x += speed * dt;
+ *   drawSprite({ textureId: tex, x: player.x, y: player.y, w: 32, h: 32 });
+ * });
  */
 export function onFrame(callback: () => void): void {
   (globalThis as any).__frameCallback = callback;
@@ -13,7 +23,10 @@ export function onFrame(callback: () => void): void {
 
 /**
  * Get the time elapsed since the last frame, in seconds.
+ * Typical values: ~0.016 at 60fps, ~0.033 at 30fps.
  * Returns 0 in headless mode.
+ *
+ * @returns Delta time in seconds (fractional).
  */
 export function getDeltaTime(): number {
   if (!hasRenderOps) return 0;

package/src/rendering/sprites.ts

@@ -7,7 +7,29 @@ const hasRenderOps =
 
 /**
  * Queue a sprite to be drawn this frame.
- * No-op in headless mode (Node or V8 test runner).
+ * Must be called every frame -- sprites are not persisted between frames.
+ * No-op in headless mode (safe to import in game logic).
+ *
+ * @param opts - Sprite rendering options (position, size, texture, layer, UV, tint).
+ *
+ * @example
+ * drawSprite({
+ *   textureId: playerTex,
+ *   x: player.x, y: player.y,
+ *   w: 32, h: 32,
+ *   layer: 1,
+ * });
+ *
+ * @example
+ * // Draw a tinted, atlas-based sprite
+ * drawSprite({
+ *   textureId: atlas,
+ *   x: 100, y: 200,
+ *   w: 16, h: 16,
+ *   uv: { x: 0.25, y: 0, w: 0.25, h: 0.5 },
+ *   tint: { r: 1, g: 0.5, b: 0.5, a: 1 },
+ *   layer: 5,
+ * });
  */
 export function drawSprite(opts: SpriteOptions): void {
   if (!hasRenderOps) return;
@@ -52,6 +74,7 @@ export function drawSprite(opts: SpriteOptions): void {
 
 /**
  * Clear all queued sprites for this frame.
+ * Normally not needed -- the renderer clears automatically at frame start.
  * No-op in headless mode.
  */
 export function clearSprites(): void {