bloody-engine 1.0.9 → 1.0.11

package/README.md

@@ -22,6 +22,38 @@ A WebGL-based 2.5D graphics engine for isometric rendering on Node.js, written i
 npm install bloody-engine
 ```
 
+## Understanding Coordinate Systems
+
+**⚠️ IMPORTANT**: Before building your game, understand the coordinate systems to avoid inverted controls!
+
+Bloody Engine uses different coordinate systems for different purposes. Mixing these up is the #1 cause of inverted controls.
+
+### Quick Summary
+
+| System | Used For | Y-Axis | Example |
+|--------|----------|--------|---------|
+| **Grid Space** | Game logic, entity positions | Y-UP (↓ Y = North/Up) | `entity.move(0, -1, 0)` moves up on screen |
+| **Screen Space** | Rendering, camera, mouse | Y-DOWN (↓ Y = Down) | `camera.y += 10` moves camera down |
+
+**Golden Rule**: Use grid space for game logic, transform to screen space only for rendering.
+
+### Common Mistake
+
+❌ **Wrong**: `camera.y += 1` for "up" movement (moves down on screen!)
+✅ **Right**: Use direction deltas: `entity.move(0, -1, 0)` for North
+
+### WASD Controls
+
+| Key | Direction | Delta | Screen Effect |
+|-----|-----------|-------|---------------|
+| **W** / ↑ | North | `{dx: 0, dy: -1}` | ✅ Up |
+| **S** / ↓ | South | `{dx: 0, dy: 1}` | ✅ Down |
+| **A** / ← | West | `{dx: -1, dy: 0}` | ✅ Left |
+| **D** / → | East | `{dx: 1, dy: 0}` | ✅ Right |
+
+📖 **Full Guide**: [docs/COORDINATE_SYSTEMS.md](docs/COORDINATE_SYSTEMS.md)
+🚀 **Interactive Demo**: Run `npm run demo:coordinates` after building
+
 ## API Overview
 
 ### Core Graphics

package/dist/node/index.js

@@ -3963,6 +3963,39 @@ class Entity {
   get previousState() {
     return this._previousState;
   }
+  /**
+   * Get position as floats (for smooth movement and rendering)
+   * Returns a copy to prevent mutation
+   */
+  getPosition() {
+    return {
+      x: this._state.gridPos.xgrid,
+      y: this._state.gridPos.ygrid,
+      z: this._state.gridPos.zheight
+    };
+  }
+  /**
+   * Get grid position as integers (for logic that needs discrete cells)
+   * Uses Math.floor for consistent cell mapping
+   */
+  getGridPos() {
+    return {
+      x: Math.floor(this._state.gridPos.xgrid),
+      y: Math.floor(this._state.gridPos.ygrid),
+      z: Math.floor(this._state.gridPos.zheight)
+    };
+  }
+  /**
+   * Get rounded grid position (nearest integer)
+   * Uses Math.round for picking/clicking operations
+   */
+  getRoundedGridPos() {
+    return {
+      x: Math.round(this._state.gridPos.xgrid),
+      y: Math.round(this._state.gridPos.ygrid),
+      z: Math.round(this._state.gridPos.zheight)
+    };
+  }
   /**
    * Store current state as previous state before updating
    */
@@ -3975,10 +4008,18 @@ class Entity {
   }
   /**
    * Set grid position directly (instant movement)
+   * Accepts floats for sub-grid positioning
    */
   setGridPos(x, y, z = 0) {
     this._state.gridPos = { xgrid: x, ygrid: y, zheight: z };
   }
+  /**
+   * Set position using integers (for discrete grid movement)
+   * Convenience method for logic that works with integer coordinates
+   */
+  setGridPosInt(x, y, z = 0) {
+    this._state.gridPos = { xgrid: x, ygrid: y, zheight: z };
+  }
   /**
    * Set velocity for continuous movement
    */
@@ -3987,13 +4028,26 @@ class Entity {
     this._state.isMoving = x !== 0 || y !== 0 || z !== 0;
   }
   /**
-   * Move by grid coordinates
+   * Move by relative amount
+   * Accepts floats for smooth, sub-grid movement
+   * @param dx Movement in X (can be fractional)
+   * @param dy Movement in Y (can be fractional)
+   * @param dz Movement in Z (can be fractional)
    */
   move(dx, dy, dz = 0) {
     this._state.gridPos.xgrid += dx;
     this._state.gridPos.ygrid += dy;
     this._state.gridPos.zheight += dz;
   }
+  /**
+   * Move by integer grid cells (for discrete movement)
+   * Convenience method for logic that needs whole-cell movement
+   */
+  moveGridCells(dx, dy, dz = 0) {
+    this._state.gridPos.xgrid += Math.floor(dx);
+    this._state.gridPos.ygrid += Math.floor(dy);
+    this._state.gridPos.zheight += Math.floor(dz);
+  }
   /**
    * Set rotation angle (in radians)
    */
@@ -4008,7 +4062,8 @@ class Entity {
   }
   /**
    * Update entity based on velocity and delta time
-   * Returns true if position changed
+   * Now properly tracks fractional movement for smooth animation
+   * Returns true if position changed (by any amount)
    */
   updateVelocity(dt) {
     if (!this._state.isMoving) {
@@ -4017,15 +4072,10 @@ class Entity {
     const dx = this._state.velocity.x * this._state.speed * dt;
     const dy = this._state.velocity.y * this._state.speed * dt;
     const dz = this._state.velocity.z * this._state.speed * dt;
-    if (Math.abs(dx) >= 1 || Math.abs(dy) >= 1 || Math.abs(dz) >= 1) {
-      this.move(
-        Math.sign(dx),
-        Math.sign(dy),
-        Math.sign(dz)
-      );
-      return true;
-    }
-    return false;
+    this._state.gridPos.xgrid += dx;
+    this._state.gridPos.ygrid += dy;
+    this._state.gridPos.zheight += dz;
+    return dx !== 0 || dy !== 0 || dz !== 0;
   }
   /**
    * Clone this entity (for state snapshots)
@@ -4041,6 +4091,7 @@ class Entity {
   }
   /**
    * Serialize entity state for transmission/saving
+   * Preserves floating-point positions for smooth movement
    */
   serialize() {
     return JSON.stringify({

package/dist/node/simulation/entity.d.ts

@@ -2,6 +2,9 @@ import { GridCoord } from '../rendering/projection';
 /**
  * Entity state at a specific point in time
  * Used for state interpolation and deterministic replay
+ *
+ * Position is stored as floats for smooth, continuous movement.
+ * Use getGridPos() to get integer grid coordinates when needed.
  */
 export interface EntityState {
     gridPos: GridCoord;
@@ -32,22 +35,64 @@ export declare class Entity {
      * Get previous entity state (for interpolation)
      */
     get previousState(): Readonly<EntityState>;
+    /**
+     * Get position as floats (for smooth movement and rendering)
+     * Returns a copy to prevent mutation
+     */
+    getPosition(): {
+        x: number;
+        y: number;
+        z: number;
+    };
+    /**
+     * Get grid position as integers (for logic that needs discrete cells)
+     * Uses Math.floor for consistent cell mapping
+     */
+    getGridPos(): {
+        x: number;
+        y: number;
+        z: number;
+    };
+    /**
+     * Get rounded grid position (nearest integer)
+     * Uses Math.round for picking/clicking operations
+     */
+    getRoundedGridPos(): {
+        x: number;
+        y: number;
+        z: number;
+    };
     /**
      * Store current state as previous state before updating
      */
     saveState(): void;
     /**
      * Set grid position directly (instant movement)
+     * Accepts floats for sub-grid positioning
      */
     setGridPos(x: number, y: number, z?: number): void;
+    /**
+     * Set position using integers (for discrete grid movement)
+     * Convenience method for logic that works with integer coordinates
+     */
+    setGridPosInt(x: number, y: number, z?: number): void;
     /**
      * Set velocity for continuous movement
      */
     setVelocity(x: number, y: number, z?: number): void;
     /**
-     * Move by grid coordinates
+     * Move by relative amount
+     * Accepts floats for smooth, sub-grid movement
+     * @param dx Movement in X (can be fractional)
+     * @param dy Movement in Y (can be fractional)
+     * @param dz Movement in Z (can be fractional)
      */
     move(dx: number, dy: number, dz?: number): void;
+    /**
+     * Move by integer grid cells (for discrete movement)
+     * Convenience method for logic that needs whole-cell movement
+     */
+    moveGridCells(dx: number, dy: number, dz?: number): void;
     /**
      * Set rotation angle (in radians)
      */
@@ -58,7 +103,8 @@ export declare class Entity {
     setSpeed(speed: number): void;
     /**
      * Update entity based on velocity and delta time
-     * Returns true if position changed
+     * Now properly tracks fractional movement for smooth animation
+     * Returns true if position changed (by any amount)
      */
     updateVelocity(dt: number): boolean;
     /**
@@ -67,6 +113,7 @@ export declare class Entity {
     clone(): Entity;
     /**
      * Serialize entity state for transmission/saving
+     * Preserves floating-point positions for smooth movement
      */
     serialize(): string;
     /**

package/dist/node/simulation/entity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"entity.d.ts","sourceRoot":"","sources":["../../../src/simulation/entity.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAEzD;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,SAAS,CAAC;IACnB,QAAQ,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9C,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED;;;GAGG;AACH,qBAAa,MAAM;IACjB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,MAAM,CAAc;IAC5B,OAAO,CAAC,cAAc,CAAc;gBAExB,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,YAAY,GAAE,OAAO,CAAC,WAAW,CAAM;IAkB7E;;OAEG;IACH,IAAI,KAAK,IAAI,QAAQ,CAAC,WAAW,CAAC,CAEjC;IAED;;OAEG;IACH,IAAI,aAAa,IAAI,QAAQ,CAAC,WAAW,CAAC,CAEzC;IAED;;OAEG;IACH,SAAS,IAAI,IAAI;IAQjB;;OAEG;IACH,UAAU,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,GAAE,MAAU,GAAG,IAAI;IAIrD;;OAEG;IACH,WAAW,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,GAAE,MAAU,GAAG,IAAI;IAKtD;;OAEG;IACH,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,GAAE,MAAU,GAAG,IAAI;IAMlD;;OAEG;IACH,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAIhC;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAI7B;;;OAGG;IACH,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAuBnC;;OAEG;IACH,KAAK,IAAI,MAAM;IAUf;;OAEG;IACH,SAAS,IAAI,MAAM;IAQnB;;OAEG;IACH,MAAM,CAAC,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAMxC;;;OAGG;IACG,eAAe,IAAI,OAAO,CAAC,UAAU,CAAC;IAM5C;;;;OAIG;WACU,iBAAiB,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC;IAMjE;;;;OAIG;IACH,YAAY,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI;IAQtC;;;OAGG;IACH,YAAY,IAAI,WAAW;CAO5B"}
+{"version":3,"file":"entity.d.ts","sourceRoot":"","sources":["../../../src/simulation/entity.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAEzD;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,SAAS,CAAC;IACnB,QAAQ,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9C,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED;;;GAGG;AACH,qBAAa,MAAM;IACjB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,MAAM,CAAc;IAC5B,OAAO,CAAC,cAAc,CAAc;gBAExB,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,YAAY,GAAE,OAAO,CAAC,WAAW,CAAM;IAkB7E;;OAEG;IACH,IAAI,KAAK,IAAI,QAAQ,CAAC,WAAW,CAAC,CAEjC;IAED;;OAEG;IACH,IAAI,aAAa,IAAI,QAAQ,CAAC,WAAW,CAAC,CAEzC;IAED;;;OAGG;IACH,WAAW,IAAI;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE;IAQlD;;;OAGG;IACH,UAAU,IAAI;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE;IAQjD;;;OAGG;IACH,iBAAiB,IAAI;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE;IAQxD;;OAEG;IACH,SAAS,IAAI,IAAI;IAQjB;;;OAGG;IACH,UAAU,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,GAAE,MAAU,GAAG,IAAI;IAIrD;;;OAGG;IACH,aAAa,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,GAAE,MAAU,GAAG,IAAI;IAIxD;;OAEG;IACH,WAAW,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,GAAE,MAAU,GAAG,IAAI;IAKtD;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,GAAE,MAAU,GAAG,IAAI;IAMlD;;;OAGG;IACH,aAAa,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,GAAE,MAAU,GAAG,IAAI;IAM3D;;OAEG;IACH,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAIhC;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAI7B;;;;OAIG;IACH,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAkBnC;;OAEG;IACH,KAAK,IAAI,MAAM;IAUf;;;OAGG;IACH,SAAS,IAAI,MAAM;IAQnB;;OAEG;IACH,MAAM,CAAC,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAMxC;;;OAGG;IACG,eAAe,IAAI,OAAO,CAAC,UAAU,CAAC;IAM5C;;;;OAIG;WACU,iBAAiB,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC;IAMjE;;;;OAIG;IACH,YAAY,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI;IAQtC;;;OAGG;IACH,YAAY,IAAI,WAAW;CAO5B"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bloody-engine",
-  "version": "1.0.9",
+  "version": "1.0.11",
   "description": "A WebGL-based 2.5D graphics engine for isometric rendering",
   "license": "MIT",
   "type": "module",
@@ -42,6 +42,7 @@
     "build:node": "vite build --config vite.config.node.ts",
     "build:demo": "vite build --config vite.config.demo.ts",
     "demo": "npm run build:demo && node dist/demo/index.js",
+    "demo:coordinates": "npm run build && node dist/node/examples/coordinate-systems-demo.js",
     "test:visual": "node test-visual.js",
     "test:determinism": "node test-determinism.js",
     "test": "vitest run",