@fonsecabarreto/genesis-gl-core 0.1.0 → 0.1.2

package/dist/Game/controls/KeyboardInput.d.ts

@@ -1,8 +1,8 @@
-import '../../Camera-DY_8gx3C.js';
+import '../../Camera-CJVYy9fH.js';
 import '../../KeyboardControl-5w7Vm0J0.js';
-export { K as KeyboardInput } from '../../KeyboardInput-DTsfj3tE.js';
+export { K as KeyboardInput } from '../../KeyboardInput-1xOAabI0.js';
 import 'gl-matrix';
 import '../../Core/domain/interfaces/Vectors.js';
-import '../../Model-CQvDXd-b.js';
+import '../../Model-BBZHnUp1.js';
 import '../../WebGLCore-DR7ZHJB0.js';
-import '../../Material-BGLkldxv.js';
+import '../../Material-DhwSRbP2.js';

package/dist/Game/index.d.ts

@@ -1,11 +1,15 @@
-export { A as AnimationController, a as AnimationState, b as AnimationTransition, C as Character, K as KeyboardInput, T as TransitionCondition } from '../KeyboardInput-DTsfj3tE.js';
-import { g as Mesh } from '../Model-CQvDXd-b.js';
-import { b as Material } from '../Material-BGLkldxv.js';
-import '../Camera-DY_8gx3C.js';
+import { P as PhysicsBody } from '../KeyboardInput-1xOAabI0.js';
+export { A as AnimationController, a as AnimationState, b as AnimationTransition, C as Character, K as KeyboardInput, T as TransitionCondition } from '../KeyboardInput-1xOAabI0.js';
+import { g as Mesh, i as Model, S as Skeleton } from '../Model-BBZHnUp1.js';
+import { b as Material } from '../Material-DhwSRbP2.js';
+import { Vector3 } from '../Core/domain/interfaces/Vectors.js';
+import { W as WebGLCore } from '../WebGLCore-DR7ZHJB0.js';
+import { Scene } from '../Core/classes/Scene.js';
+import { Viewport } from '../Core/classes/Viewport.js';
+import { Renderer } from '../Core/classes/Renderer.js';
+import '../Camera-CJVYy9fH.js';
 import 'gl-matrix';
-import '../Core/domain/interfaces/Vectors.js';
 import '../KeyboardControl-5w7Vm0J0.js';
-import '../WebGLCore-DR7ZHJB0.js';
 
 declare class Arm extends Mesh {
     private swingPhase;
@@ -42,4 +46,301 @@ declare class Leg extends Mesh {
     animate(moving: boolean, deltaTime: number): number;
 }
 
-export { Arm, Head, Leg };
+/**
+ * Actor — a static, non-physics scene entity.
+ *
+ * Sits directly on top of {@link Model} and represents any object that is
+ * placed in the world but **does not move** (environment props, decorations,
+ * landmarks, triggers, etc.).
+ *
+ * Use {@link InteractiveActor} when the object should react to collisions
+ * and participate in the physics simulation loop.
+ *
+ * ## Layer contract
+ * ```
+ * Model        → transform, AABB, render, skeletal animation
+ *   └─ Actor          → static scene entity (no physics)
+ *   └─ PhysicsBody    → + velocity, gravity, ground detection, friction
+ *        └─ Character   → + input, animation FSM, jump/roll, stamina
+ *        └─ InteractiveActor → + bounce, rolling friction, impulse exchange
+ * ```
+ *
+ * ## Usage
+ * ```ts
+ * const prop = new Actor(myModel.meshes, [10, 0, 5], [1, 1, 1], 'lamp_post');
+ * prop.collidable = false; // decorative — skip collision
+ * scene.add('lamp_0', prop);
+ * ```
+ */
+declare class Actor extends Model {
+    constructor(meshes: Mesh[], translation?: Vector3, scale?: Vector3, name?: string, skeleton?: Skeleton | null);
+}
+
+/**
+ * InteractiveActor — a physics-simulated scene object.
+ *
+ * Extends {@link PhysicsBody} with:
+ * - Bounce behaviour via {@link restitution}.
+ * - Horizontal friction via the inherited {@link surfaceFriction}.
+ * - An override of {@link resolveYCollision} that applies a bounce impulse.
+ * - An override of {@link update} that integrates velocity and applies friction.
+ *
+ * The constructor accepts any set of {@link Mesh}es so any model can behave
+ * as a physics-interactive object.  Use the static factory {@link sphere} when
+ * you specifically want a procedural sphere shape.
+ *
+ * ## Usage — custom mesh
+ * ```ts
+ * const actor = new InteractiveActor(myModel.meshes, [0, 5, 0], 'crate');
+ * actor.restitution = 0.2;
+ * game.addPhysicsObject('crate_1', actor);
+ * ```
+ *
+ * ## Usage — sphere shorthand
+ * ```ts
+ * const ball = InteractiveActor.sphere(webglCore, mat, 0.5, [0, 5, 0]);
+ * game.addPhysicsObject('ball_1', ball);
+ * ```
+ */
+declare class InteractiveActor extends PhysicsBody {
+    /**
+     * Minimum impact speed (|vy|) required to trigger a visible bounce.
+     * Below this threshold the actor comes to rest instead of micro-bouncing.
+     * Default: `0.05`.
+     */
+    minBounceSpeed: number;
+    constructor(meshes: Mesh[], position?: Vector3, name?: string);
+    /**
+     * Create an {@link InteractiveActor} with a procedurally generated sphere
+     * mesh — convenience shorthand for the common "physics ball" use case.
+     *
+     * @param webglCore  WebGL context used to build the mesh buffers.
+     * @param material   Material applied to the sphere.
+     * @param radius     Sphere radius in world units. Default `0.5`.
+     * @param position   Initial world position. Default origin.
+     * @param latBands   Latitude subdivisions. Default `16`.
+     * @param lonBands   Longitude subdivisions. Default `16`.
+     */
+    static sphere(webglCore: WebGLCore, material: Material, radius?: number, position?: Vector3, latBands?: number, lonBands?: number): InteractiveActor;
+    /**
+     * Apply a bounce impulse instead of zeroing Y velocity.
+     * The collision system passes the velocity captured just before impact so
+     * the correct outgoing speed can be computed from {@link restitution}.
+     */
+    resolveYCollision(impactVy: number): void;
+    /**
+     * Advance one physics tick: integrate velocity, apply friction, zero
+     * sub-threshold components so the actor eventually comes to rest.
+     */
+    update(deltaTime: number): void;
+}
+
+/**
+ * GameLoopRunner
+ *
+ * Encapsulates a fixed-timestep game loop built on `requestAnimationFrame`.
+ *
+ * Responsibilities:
+ *  - Accumulate real elapsed time and fire a fixed-update callback at a
+ *    constant rate (e.g. 60 Hz physics / logic ticks).
+ *  - Fire a variable-rate render callback once per animation frame.
+ *  - Expose start / stop / dispose controls.
+ *
+ * Design note: this class has no knowledge of scene, renderer, or any game
+ * object — it is a pure scheduling primitive consumed by `GameApplication`.
+ */
+declare class GameLoopRunner {
+    readonly targetFPS: number;
+    /** Number of milliseconds between each fixed-update tick. */
+    private readonly stepMs;
+    private rafHandle;
+    private lastTime;
+    private accumulated;
+    private fixedUpdateFn;
+    private renderFn;
+    /**
+     * @param targetFPS  Number of fixed-update ticks per second. Defaults to 60.
+     */
+    constructor(targetFPS?: number);
+    /**
+     * Begin the loop.
+     *
+     * @param fixedUpdate  Called at the fixed timestep rate with `dt` in seconds.
+     * @param render       Called once per animation frame (variable rate).
+     */
+    start(fixedUpdate: (dt: number) => void, render: () => void): void;
+    /** Pause the loop without discarding callbacks. Resume with `resume()`. */
+    pause(): void;
+    /** Resume a paused loop. */
+    resume(): void;
+    /** Stop the loop and release all callbacks. */
+    stop(): void;
+    get isRunning(): boolean;
+    /** Arrow function to preserve `this` across rAF callbacks. */
+    private readonly tick;
+}
+
+/**
+ * Bootstrap configuration passed to `GameApplication`.
+ *
+ * All fields except `canvasId` are optional and fall back to sensible defaults.
+ */
+interface GameApplicationConfig {
+    /** ID of the `<canvas>` element that WebGL will render into. */
+    canvasId: string;
+    /** Logical render width in pixels. Default: `1280`. */
+    viewportWidth?: number;
+    /** Logical render height in pixels. Default: `720`. */
+    viewportHeight?: number;
+    /**
+     * Number of fixed-update ticks per second.
+     * Physics, input and game-logic run at this rate. Default: `60`.
+     */
+    targetFPS?: number;
+}
+type ResolvedConfig = Required<GameApplicationConfig>;
+/**
+ * GameApplication — abstract base class for GenesisGL games.
+ *
+ * ## Design: Template Method pattern
+ *
+ * This class provides the **invariant algorithm skeleton** for a GenesisGL
+ * application. Subclasses supply the variant behaviour by overriding the
+ * hook methods listed below.
+ *
+ * ### Lifecycle
+ *
+ * ```
+ * start()
+ *  ├── onLoadResources()   ← abstract — load models, textures, data
+ *  ├── createScene()       ← virtual  — build and configure the Scene
+ *  ├── createViewport()    ← virtual  — build and configure the Viewport
+ *  ├── createRenderer()    ← virtual  — build and configure the Renderer
+ *  ├── onInit()            ← abstract — place entities, wire input, etc.
+ *  └── loop (per frame)
+ *       ├── [N×] onUpdate(dt)    ← abstract — physics / logic fixed tick
+ *       ├── onBeforeRender()     ← virtual  — pre-render hook (e.g. HUD)
+ *       ├── renderer.render()   ← sealed
+ *       └── onAfterRender()     ← virtual  — post-render hook
+ *
+ * stop()
+ *  └── onDispose()         ← virtual  — release custom resources
+ * ```
+ *
+ * ### Minimal subclass
+ *
+ * ```ts
+ * class MyGame extends GameApplication {
+ *   protected async onLoadResources() { ... }
+ *   protected async onInit()          { ... }
+ *   protected onUpdate(dt: number)    { ... }
+ * }
+ *
+ * const game = new MyGame({ canvasId: 'glcanvas' });
+ * await game.start();
+ * ```
+ */
+declare abstract class GameApplication {
+    protected readonly webglCore: WebGLCore;
+    protected readonly config: ResolvedConfig;
+    /**
+     * The active scene. Populated during construction via `createScene()`
+     * so subclasses may reference it as early as `onLoadResources()`.
+     */
+    protected readonly scene: Scene;
+    /**
+     * Set during `start()`, after `onLoadResources()` returns.
+     * Use in `onInit()` and lifecycle hooks.
+     */
+    viewport: Viewport | null;
+    /**
+     * Set during `start()`, after `viewport` is initialised.
+     * `null` before `start()` resolves — safe to check from external code.
+     */
+    renderer: Renderer | null;
+    private readonly loopRunner;
+    private _started;
+    constructor(config: GameApplicationConfig);
+    /**
+     * Execute the full startup sequence and begin the game loop.
+     *
+     * The sequence is **sealed** — extend behaviour through the protected hooks,
+     * not by overriding `start()`.
+     */
+    start(): Promise<void>;
+    /**
+     * Pause the game loop without discarding state.
+     * Call `resume()` to continue.
+     */
+    pause(): void;
+    /** Resume a paused game loop. */
+    resume(): void;
+    /**
+     * Stop the game loop permanently and invoke `onDispose()`.
+     * After calling `stop()` the instance should be discarded.
+     */
+    stop(): void;
+    get isRunning(): boolean;
+    /**
+     * Load all external assets required by the game (models, textures, data).
+     *
+     * Called **before** `viewport`, `renderer`, or any scene entities are
+     * created, so it is safe to fire async fetch/XHR calls here.
+     */
+    protected abstract onLoadResources(): Promise<void>;
+    /**
+     * Place entities into the scene, configure input handlers, set up stores, etc.
+     *
+     * Called once, after `viewport` and `renderer` have been initialised and
+     * `onLoadResources()` has resolved.
+     */
+    protected abstract onInit(): Promise<void> | void;
+    /**
+     * Game-logic / physics update.
+     *
+     * Called at the fixed timestep rate defined by `config.targetFPS`.
+     *
+     * @param dt  Fixed delta-time in **seconds** (e.g. `1/60 ≈ 0.0167`).
+     */
+    protected abstract onUpdate(dt: number): void;
+    /**
+     * Factory for the `Scene`. Override to customise lights or initial state.
+     * Default: `Scene.withDefaultLights(webglCore)`.
+     */
+    protected createScene(): Scene;
+    /**
+     * Factory for the `Viewport`. Override to customise camera settings or
+     * attach extra resize behaviour.
+     * Default: constructed from `config.canvasId`, `viewportWidth`, `viewportHeight`.
+     */
+    protected createViewport(): Viewport;
+    /**
+     * Factory for the `Renderer`. Override to enable debug mode or swap
+     * the renderer implementation.
+     * Default: `new Renderer(webglCore, viewport)`.
+     */
+    protected createRenderer(): Renderer;
+    /**
+     * Called every animation frame **before** `renderer.render(scene)`.
+     *
+     * Suitable for: updating HUD overlays, syncing camera state, or any
+     * visual concern that must run at display rate rather than the fixed tick.
+     */
+    protected onBeforeRender(): void;
+    /**
+     * Called every animation frame **after** `renderer.render(scene)`.
+     *
+     * Suitable for: post-process passes, 2D canvas overlays, analytics.
+     */
+    protected onAfterRender(): void;
+    /**
+     * Called by `stop()` to release any custom resources held by the subclass
+     * (event listeners, WebSocket connections, audio contexts, etc.).
+     *
+     * The base `Scene` and engine objects are **not** auto-disposed here;
+     * call `scene.dispose()` explicitly if needed.
+     */
+    protected onDispose(): void;
+}
+
+export { Actor, Arm, GameApplication, type GameApplicationConfig, GameLoopRunner, Head, InteractiveActor, Leg, PhysicsBody };