@fonsecabarreto/genesis-gl-core 0.1.0 → 0.1.1

package/dist/Game/index.js

@@ -3,14 +3,22 @@ import {
 } from "../chunk-P7QOKDLY.js";
 import "../chunk-SUNYSY45.js";
 import {
-  Mesh
-} from "../chunk-QCQVJCSR.js";
-import "../chunk-6LS6AO5H.js";
+  Mesh,
+  Renderer,
+  WebGLCore
+} from "../chunk-ZCJ3MJZD.js";
+import {
+  Material
+} from "../chunk-L66K4AZU.js";
 import {
   Model
-} from "../chunk-JK2HEZAT.js";
-import "../chunk-3ULETMWF.js";
-import "../chunk-5TAAXI6S.js";
+} from "../chunk-QOAQVTAB.js";
+import {
+  Scene
+} from "../chunk-3ULETMWF.js";
+import {
+  Viewport
+} from "../chunk-XMW2MS66.js";
 
 // src/Game/classes/AnimationController.ts
 var AnimationController = class {
@@ -76,32 +84,96 @@ var AnimationController = class {
   }
 };
 
-// src/Game/classes/Character.ts
-var Character = class extends Model {
-  id;
-  health = 100;
-  /** Friction applied when grounded — updated from the surface material on landing.
-   *  0 = no resistance (pure ice), 1 = instant stop. */
+// src/Game/classes/PhysicsBody.ts
+var PhysicsBody = class extends Model {
+  // ── Linear dynamics ───────────────────────────────────────────────────────
+  /** World-space velocity in units/second (XYZ). */
+  velocity = [0, 0, 0];
+  /**
+   * When `true` the owning physics step should add gravity to `velocity[1]`
+   * every tick.  Set to `false` for server-driven actors whose Y position is
+   * authoritative from the network and must not be locally simulated.
+   */
+  useGravity = true;
+  // ── Surface interaction ───────────────────────────────────────────────────
+  /**
+   * Friction coefficient of the surface this body is currently standing on.
+   * Updated on landing from the collided model's material.
+   * Range: 0 (pure ice) → 1 (instant stop).
+   */
   surfaceFriction = 0.3;
-  /** Horizontal damping while airborne. 0 = no air drag, 1 = instant stop. */
+  /**
+   * Horizontal damping applied while airborne.
+   * Kept low so air strafing feels natural and not floaty.
+   */
   airFriction = 0.02;
-  speed = 0.2;
-  stamina = 10;
-  velocity = [0, 0, 0];
+  // ── Mass & restitution ────────────────────────────────────────────────────
+  /**
+   * Mass in kilograms.  Used to distribute impulses proportionally when two
+   * dynamic bodies collide: heavier objects are displaced and accelerated
+   * less.  Default: `1.0`.  Set higher for heavy objects (e.g. boulders) or
+   * lower for light ones (e.g. beach balls).
+   */
+  mass = 1;
+  /**
+   * Coefficient of restitution — fraction of relative velocity preserved
+   * along the collision normal.  Range: 0 (perfectly inelastic) → 1 (fully
+   * elastic).  Default: `0` (rigid body, no bounce).  `Ball` overrides this
+   * to `0.6`.  When two bodies collide the effective restitution is the
+   * geometric mean of both values.
+   */
+  restitution = 0;
+  // ── Ground state ──────────────────────────────────────────────────────────
   _isGrounded = false;
-  /** Setting to true (landing) resets the jump counter. */
   get isGrounded() {
     return this._isGrounded;
   }
+  /**
+   * Setting to `true` when the previous state was `false` triggers
+   * the `onLand()` hook — override in subclasses for gameplay responses
+   * (e.g. landing roll, jump counter reset).
+   */
   set isGrounded(v) {
-    if (v && !this._isGrounded) {
-      const hardLanding = this.velocity[1] <= this.minLandingImpact;
-      if (this.isInputActive && hardLanding) this._landingRoll = true;
-      this._jumpsUsed = 0;
-      this.isDoubleJumping = false;
-    }
+    const wasGrounded = this._isGrounded;
     this._isGrounded = v;
+    if (v && !wasGrounded) {
+      this.onLand();
+    }
+  }
+  // ── Constructor ───────────────────────────────────────────────────────────
+  constructor(meshes, translation = [0, 0, 0], scale = [1, 1, 1], name = "physicsBody", skeleton = null) {
+    super(meshes, translation, scale, name, skeleton);
+  }
+  // ── Virtual hooks ─────────────────────────────────────────────────────────
+  /**
+   * Called once when this body transitions from airborne to grounded.
+   * Override to add gameplay responses (landing roll, sound, VFX, etc.).
+   * Base implementation does nothing.
+   */
+  onLand() {
   }
+  /**
+   * Called by the collision system when a vertical (Y-axis) surface is hit.
+   * Receives the velocity **at the moment of impact** so subclasses can
+   * compute a bounce impulse before the caller updates `velocity[1]`.
+   *
+   * Default: zero out vertical velocity (rigid body, no bounce).
+   * Override in `Ball` (or any bouncy actor) to apply a restitution impulse.
+   *
+   * @param impactVy  `velocity[1]` captured just before the collision resolve.
+   */
+  resolveYCollision(impactVy) {
+    void impactVy;
+    this.velocity[1] = 0;
+  }
+};
+
+// src/Game/classes/Character.ts
+var Character = class extends PhysicsBody {
+  id;
+  health = 100;
+  speed = 0.2;
+  stamina = 10;
   /** Pending auto-roll on landing after a double jump. */
   _landingRoll = false;
   /** Minimum downward impact speed (negative Y velocity) required to trigger
@@ -136,6 +208,16 @@ var Character = class extends Model {
   // seconds
   _jumpsUsed = 0;
   maxJumps = 2;
+  /**
+   * Called by {@link PhysicsBody.isGrounded} setter on every landing.
+   * Queues a landing roll if the impact was hard enough and resets jump state.
+   */
+  onLand() {
+    const hardLanding = this.velocity[1] <= this.minLandingImpact;
+    if (this.isInputActive && hardLanding) this._landingRoll = true;
+    this._jumpsUsed = 0;
+    this.isDoubleJumping = false;
+  }
   constructor(id, baseModel) {
     super(
       baseModel.meshes,
@@ -342,12 +424,376 @@ var Leg = class extends Mesh {
     }
   }
 };
+
+// src/Game/classes/Actor.ts
+var Actor = class extends Model {
+  constructor(meshes, translation = [0, 0, 0], scale = [1, 1, 1], name = "actor", skeleton = null) {
+    super(meshes, translation, scale, name, skeleton);
+  }
+};
+
+// src/Core/utils/create-sphere.ts
+function createSphereMesh(webglCore, radius = 1, latBands = 12, lonBands = 12, color = [1, 1, 1]) {
+  const positions = [];
+  const normals = [];
+  for (let lat = 0; lat <= latBands; lat++) {
+    const theta = lat * Math.PI / latBands;
+    const sinTheta = Math.sin(theta);
+    const cosTheta = Math.cos(theta);
+    for (let lon = 0; lon <= lonBands; lon++) {
+      const phi = lon * 2 * Math.PI / lonBands;
+      const sinPhi = Math.sin(phi);
+      const cosPhi = Math.cos(phi);
+      const x = cosPhi * sinTheta;
+      const y = cosTheta;
+      const z = sinPhi * sinTheta;
+      positions.push(radius * x, radius * y, radius * z);
+      normals.push(x, y, z);
+    }
+  }
+  const indices = [];
+  for (let lat = 0; lat < latBands; lat++) {
+    for (let lon = 0; lon < lonBands; lon++) {
+      const first = lat * (lonBands + 1) + lon;
+      const second = first + lonBands + 1;
+      indices.push(first, second, first + 1);
+      indices.push(second, second + 1, first + 1);
+    }
+  }
+  const vertices = [];
+  const finalNormals = [];
+  for (const idx of indices) {
+    vertices.push(
+      positions[idx * 3],
+      positions[idx * 3 + 1],
+      positions[idx * 3 + 2]
+    );
+    finalNormals.push(
+      normals[idx * 3],
+      normals[idx * 3 + 1],
+      normals[idx * 3 + 2]
+    );
+  }
+  const material = new Material(webglCore, {
+    albedoColor: [color[0], color[1], color[2], 1],
+    unlit: true
+    // lights always glow
+  });
+  return new Mesh(
+    "sphere",
+    new Float32Array(vertices),
+    new Float32Array(finalNormals),
+    material
+  );
+}
+
+// src/Game/classes/InteractiveActor.ts
+var InteractiveActor = 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 = 0.05;
+  constructor(meshes, position = [0, 0, 0], name = "interactiveActor") {
+    super(meshes, position, [1, 1, 1], name);
+  }
+  // ── Static factories ──────────────────────────────────────────────────────
+  /**
+   * 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, material, radius = 0.5, position = [0, 0, 0], latBands = 16, lonBands = 16) {
+    const mesh = createSphereMesh(
+      webglCore,
+      radius,
+      latBands,
+      lonBands,
+      material.albedoColor?.slice(0, 3) ?? [1, 1, 1]
+    );
+    mesh.material = material;
+    const actor = new _InteractiveActor([mesh], position, "ball");
+    actor.restitution = 0.6;
+    actor.surfaceFriction = 0.05;
+    return actor;
+  }
+  // ── PhysicsBody hooks ─────────────────────────────────────────────────────
+  /**
+   * 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) {
+    if (Math.abs(impactVy) > this.minBounceSpeed) {
+      this.velocity[1] = -impactVy * this.restitution;
+      this._isGrounded = false;
+    } else {
+      this.velocity[1] = 0;
+    }
+  }
+  // ── Update ────────────────────────────────────────────────────────────────
+  /**
+   * Advance one physics tick: integrate velocity, apply friction, zero
+   * sub-threshold components so the actor eventually comes to rest.
+   */
+  update(deltaTime) {
+    super.update(deltaTime);
+    if (this._isGrounded) {
+      const friction = Math.min(0.9, this.surfaceFriction + 5e-3);
+      this.velocity[0] += (0 - this.velocity[0]) * friction;
+      this.velocity[2] += (0 - this.velocity[2]) * friction;
+    } else {
+      this.velocity[0] *= 1 - this.airFriction;
+      this.velocity[2] *= 1 - this.airFriction;
+    }
+    this.move(this.velocity[0], this.velocity[1], this.velocity[2]);
+    if (Math.abs(this.velocity[0]) < 1e-3) this.velocity[0] = 0;
+    if (Math.abs(this.velocity[1]) < 1e-3) this.velocity[1] = 0;
+    if (Math.abs(this.velocity[2]) < 1e-3) this.velocity[2] = 0;
+  }
+};
+
+// src/Game/GameLoopRunner.ts
+var GameLoopRunner = class {
+  /**
+   * @param targetFPS  Number of fixed-update ticks per second. Defaults to 60.
+   */
+  constructor(targetFPS = 60) {
+    this.targetFPS = targetFPS;
+    this.stepMs = 1e3 / targetFPS;
+  }
+  targetFPS;
+  /** Number of milliseconds between each fixed-update tick. */
+  stepMs;
+  rafHandle = null;
+  lastTime = 0;
+  accumulated = 0;
+  fixedUpdateFn = null;
+  renderFn = null;
+  // ── Public API ────────────────────────────────────────────────────────────
+  /**
+   * 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, render) {
+    if (this.rafHandle !== null) {
+      console.warn(
+        "[GameLoopRunner] start() called while already running \u2014 ignoring."
+      );
+      return;
+    }
+    this.fixedUpdateFn = fixedUpdate;
+    this.renderFn = render;
+    this.lastTime = performance.now();
+    this.accumulated = 0;
+    this.rafHandle = requestAnimationFrame(this.tick);
+  }
+  /** Pause the loop without discarding callbacks. Resume with `resume()`. */
+  pause() {
+    if (this.rafHandle !== null) {
+      cancelAnimationFrame(this.rafHandle);
+      this.rafHandle = null;
+    }
+  }
+  /** Resume a paused loop. */
+  resume() {
+    if (this.rafHandle !== null) return;
+    if (!this.fixedUpdateFn || !this.renderFn) {
+      console.warn(
+        "[GameLoopRunner] resume() called before start() \u2014 ignoring."
+      );
+      return;
+    }
+    this.lastTime = performance.now();
+    this.rafHandle = requestAnimationFrame(this.tick);
+  }
+  /** Stop the loop and release all callbacks. */
+  stop() {
+    this.pause();
+    this.fixedUpdateFn = null;
+    this.renderFn = null;
+    this.accumulated = 0;
+  }
+  get isRunning() {
+    return this.rafHandle !== null;
+  }
+  // ── Private ───────────────────────────────────────────────────────────────
+  /** Arrow function to preserve `this` across rAF callbacks. */
+  tick = (now) => {
+    const elapsed = now - this.lastTime;
+    this.lastTime = now;
+    this.accumulated += Math.min(elapsed, this.stepMs * 5);
+    while (this.accumulated >= this.stepMs) {
+      this.fixedUpdateFn?.(this.stepMs / 1e3);
+      this.accumulated -= this.stepMs;
+    }
+    this.renderFn?.();
+    if (this.rafHandle !== null) {
+      this.rafHandle = requestAnimationFrame(this.tick);
+    }
+  };
+};
+
+// src/Game/GameApplication.ts
+var DEFAULT_CONFIG = {
+  viewportWidth: 1280,
+  viewportHeight: 720,
+  targetFPS: 60
+};
+var GameApplication = class {
+  // ── Core engine objects — available after construction ───────────────────
+  webglCore;
+  config;
+  /**
+   * The active scene. Populated during construction via `createScene()`
+   * so subclasses may reference it as early as `onLoadResources()`.
+   */
+  scene;
+  /**
+   * Set during `start()`, after `onLoadResources()` returns.
+   * Use in `onInit()` and lifecycle hooks.
+   */
+  viewport = null;
+  /**
+   * Set during `start()`, after `viewport` is initialised.
+   * `null` before `start()` resolves — safe to check from external code.
+   */
+  renderer = null;
+  // ── Internal ──────────────────────────────────────────────────────────────
+  loopRunner;
+  _started = false;
+  // ── Constructor ───────────────────────────────────────────────────────────
+  constructor(config) {
+    this.config = { ...DEFAULT_CONFIG, ...config };
+    this.webglCore = new WebGLCore(this.config.canvasId);
+    this.scene = this.createScene();
+    this.loopRunner = new GameLoopRunner(this.config.targetFPS);
+  }
+  // ── Public API ────────────────────────────────────────────────────────────
+  /**
+   * Execute the full startup sequence and begin the game loop.
+   *
+   * The sequence is **sealed** — extend behaviour through the protected hooks,
+   * not by overriding `start()`.
+   */
+  async start() {
+    if (this._started) {
+      console.warn(
+        "[GameApplication] start() called more than once \u2014 ignoring."
+      );
+      return;
+    }
+    this._started = true;
+    await this.onLoadResources();
+    this.viewport = this.createViewport();
+    this.renderer = this.createRenderer();
+    await this.onInit();
+    this.loopRunner.start(
+      (dt) => this.onUpdate(dt),
+      () => {
+        this.onBeforeRender();
+        this.renderer.render(this.scene);
+        this.onAfterRender();
+      }
+    );
+  }
+  /**
+   * Pause the game loop without discarding state.
+   * Call `resume()` to continue.
+   */
+  pause() {
+    this.loopRunner.pause();
+  }
+  /** Resume a paused game loop. */
+  resume() {
+    this.loopRunner.resume();
+  }
+  /**
+   * Stop the game loop permanently and invoke `onDispose()`.
+   * After calling `stop()` the instance should be discarded.
+   */
+  stop() {
+    this.loopRunner.stop();
+    this.onDispose();
+    this._started = false;
+  }
+  get isRunning() {
+    return this.loopRunner.isRunning;
+  }
+  // ── Virtual hooks (optional override) ────────────────────────────────────
+  /**
+   * Factory for the `Scene`. Override to customise lights or initial state.
+   * Default: `Scene.withDefaultLights(webglCore)`.
+   */
+  createScene() {
+    return Scene.withDefaultLights(this.webglCore);
+  }
+  /**
+   * Factory for the `Viewport`. Override to customise camera settings or
+   * attach extra resize behaviour.
+   * Default: constructed from `config.canvasId`, `viewportWidth`, `viewportHeight`.
+   */
+  createViewport() {
+    return new Viewport(
+      this.config.canvasId,
+      this.config.viewportWidth,
+      this.config.viewportHeight,
+      this.webglCore
+    );
+  }
+  /**
+   * Factory for the `Renderer`. Override to enable debug mode or swap
+   * the renderer implementation.
+   * Default: `new Renderer(webglCore, viewport)`.
+   */
+  createRenderer() {
+    return new Renderer(this.webglCore, this.viewport);
+  }
+  /**
+   * 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.
+   */
+  onBeforeRender() {
+  }
+  /**
+   * Called every animation frame **after** `renderer.render(scene)`.
+   *
+   * Suitable for: post-process passes, 2D canvas overlays, analytics.
+   */
+  onAfterRender() {
+  }
+  /**
+   * 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.
+   */
+  onDispose() {
+  }
+};
 export {
+  Actor,
   AnimationController,
   Arm,
   Character,
+  GameApplication,
+  GameLoopRunner,
   Head,
+  InteractiveActor,
   KeyboardInput,
-  Leg
+  Leg,
+  PhysicsBody
 };
 //# sourceMappingURL=index.js.map