devskill 2.0.7 → 2.0.8

package/skills/game-engine/assets/simple-2d-engine.md

@@ -0,0 +1,507 @@
+# Simple 2D Platformer Engine Template
+
+A grid-based 2D platformer engine tutorial by **Sebastien Benard** (deepnight), the lead developer behind *Dead Cells*. This template covers the fundamental architecture for a performant platformer: a dual-coordinate positioning system that blends integer grid cells with sub-pixel precision, velocity and friction mechanics, gravity, and a robust collision detection and response system. The approach is language-agnostic but examples use Haxe.
+
+**Source references:**
+- [Part 1 - Basics](https://deepnight.net/tutorial/a-simple-platformer-engine-part-1-basics/)
+- [Part 2 - Collisions](https://deepnight.net/tutorial/a-simple-platformer-engine-part-2-collisions/)
+
+**Author:** [Sebastien Benard / deepnight](https://deepnight.net)
+
+---
+
+## Engine Architecture Overview
+
+The engine is built around a grid-based world where each cell has a fixed pixel size (e.g., 16x16). Entities exist within this grid using a **dual-coordinate system**: integer cell coordinates for coarse position and floating-point ratios for sub-pixel precision within each cell. This design enables pixel-perfect collision detection against the grid while maintaining smooth, fluid movement.
+
+### Core Principles
+
+1. **Grid is truth:** The world is a 2D grid of cells. Collision data lives in the grid.
+2. **Entities straddle cells:** An entity's position is defined by which cell it occupies (`cx`, `cy`) plus how far into that cell it is (`xr`, `yr`).
+3. **Velocity is in grid-ratio units:** Movement deltas (`dx`, `dy`) represent fractions of a cell per step, not raw pixels.
+4. **Collisions are grid lookups:** Instead of testing sprite bounds against geometry, the engine checks the grid cells an entity is about to enter.
+
+---
+
+## Part 1: Basics
+
+### The Grid
+
+The level is a 2D array where each cell is either empty or solid. A constant defines the cell size in pixels:
+
+```haxe
+static inline var GRID = 16;
+```
+
+Collision data is stored as a simple 2D boolean or integer map:
+
+```haxe
+// Check if a grid cell is solid
+function hasCollision(cx:Int, cy:Int):Bool {
+  // Look up cell value in the level data
+  return level.getCollision(cx, cy) != 0;
+}
+```
+
+### Entity Positioning: Dual Coordinates
+
+Every entity tracks its position using four values:
+
+| Variable | Type | Description |
+|----------|------|-------------|
+| `cx` | Int | Cell X coordinate (which column the entity is in) |
+| `cy` | Int | Cell Y coordinate (which row the entity is in) |
+| `xr` | Float | X ratio within the cell, range 0.0 to 1.0 |
+| `yr` | Float | Y ratio within the cell, range 0.0 to 1.0 |
+
+An entity at `cx=5, cy=3, xr=0.5, yr=1.0` is horizontally centered in cell (5,3) and sitting on the bottom edge.
+
+### Converting to Pixel Coordinates
+
+To render the entity, convert grid coordinates to pixel positions:
+
+```haxe
+// Pixel position for rendering
+var pixelX : Float = (cx + xr) * GRID;
+var pixelY : Float = (cy + yr) * GRID;
+```
+
+This produces smooth, sub-pixel-precise positions for rendering even though the collision system operates on discrete grid cells.
+
+### Velocity and Movement
+
+Velocity is expressed in **cell-ratio units per fixed-step** (not pixels per frame):
+
+```haxe
+var dx : Float = 0; // Horizontal velocity (cells per step)
+var dy : Float = 0; // Vertical velocity (cells per step)
+```
+
+Each fixed-step update, velocity is added to the ratio:
+
+```haxe
+// Apply horizontal movement
+xr += dx;
+
+// Apply vertical movement
+yr += dy;
+```
+
+### Cell Overflow
+
+When the ratio exceeds the 0..1 range, the entity has moved into an adjacent cell:
+
+```haxe
+// X overflow
+while (xr > 1) { xr--; cx++; }
+while (xr < 0) { xr++; cx--; }
+
+// Y overflow
+while (yr > 1) { yr--; cy++; }
+while (yr < 0) { yr++; cy--; }
+```
+
+### Friction
+
+Friction is applied as a multiplier each step, decaying velocity toward zero:
+
+```haxe
+var frictX : Float = 0.82; // Horizontal friction (0 = instant stop, 1 = no friction)
+var frictY : Float = 0.82; // Vertical friction
+
+// Applied each step after movement
+dx *= frictX;
+dy *= frictY;
+
+// Clamp very small values to zero
+if (Math.abs(dx) < 0.0005) dx = 0;
+if (Math.abs(dy) < 0.0005) dy = 0;
+```
+
+Typical friction values:
+- `0.82` -- Standard ground friction (responsive, quick stop)
+- `0.94` -- Ice or slippery surface (slow deceleration)
+- `0.96` -- Air friction (very slow horizontal deceleration)
+
+### Gravity
+
+Gravity is a constant added to `dy` each step:
+
+```haxe
+static inline var GRAVITY = 0.05; // In cell-ratio units per step^2
+
+// In fixedUpdate:
+dy += GRAVITY;
+```
+
+Since `dy` accumulates and friction is applied, the entity reaches a natural terminal velocity.
+
+### Rendering / Sprite Sync
+
+After the physics step, the sprite is placed at the computed pixel position:
+
+```haxe
+// In postUpdate, after physics is done:
+sprite.x = (cx + xr) * GRID;
+sprite.y = (cy + yr) * GRID;
+```
+
+For a platformer character, the anchor point is typically at the bottom-center of the sprite. With `yr = 1.0` representing the bottom of the current cell, the sprite's feet align with the floor.
+
+### Basic Entity Template
+
+```haxe
+class Entity {
+  // Grid coordinates
+  var cx : Int = 0;
+  var cy : Int = 0;
+  var xr : Float = 0.5;
+  var yr : Float = 1.0;
+
+  // Velocity
+  var dx : Float = 0;
+  var dy : Float = 0;
+
+  // Friction
+  var frictX : Float = 0.82;
+  var frictY : Float = 0.82;
+
+  // Gravity
+  static inline var GRAVITY = 0.05;
+
+  // Grid size
+  static inline var GRID = 16;
+
+  // Pixel position (computed)
+  public var attachX(get, never) : Float;
+  inline function get_attachX() return (cx + xr) * GRID;
+
+  public var attachY(get, never) : Float;
+  inline function get_attachY() return (cy + yr) * GRID;
+
+  public function fixedUpdate() {
+    // Gravity
+    dy += GRAVITY;
+
+    // Apply velocity
+    xr += dx;
+    yr += dy;
+
+    // Apply friction
+    dx *= frictX;
+    dy *= frictY;
+
+    // Clamp small values
+    if (Math.abs(dx) < 0.0005) dx = 0;
+    if (Math.abs(dy) < 0.0005) dy = 0;
+
+    // Cell overflow
+    while (xr > 1) { xr--; cx++; }
+    while (xr < 0) { xr++; cx--; }
+    while (yr > 1) { yr--; cy++; }
+    while (yr < 0) { yr++; cy--; }
+  }
+
+  public function postUpdate() {
+    sprite.x = attachX;
+    sprite.y = attachY;
+  }
+}
+```
+
+---
+
+## Part 2: Collisions
+
+### Collision Philosophy
+
+Instead of using bounding-box-to-bounding-box collision detection (which becomes complex with slopes, one-way platforms, and edge cases), this engine checks grid cells directly. Since the entity's position is already expressed in grid terms, collision detection becomes a series of simple integer lookups.
+
+### The Core Idea
+
+Before allowing the entity to move into a neighboring cell, check if that cell is solid. If it is, clamp the entity's ratio and zero out its velocity on that axis.
+
+### Axis Separation
+
+Collisions are handled **per axis** -- first X, then Y (or vice versa). This simplifies the logic and avoids corner-case tunneling issues.
+
+### X-Axis Collision
+
+After applying `dx` to `xr`, before doing the cell-overflow step, check for collisions:
+
+```haxe
+// Apply X movement
+xr += dx;
+
+// Check collision to the RIGHT
+if (dx > 0 && hasCollision(cx + 1, cy) && xr >= 0.7) {
+  xr = 0.7;   // Clamp: stop before entering the solid cell
+  dx = 0;     // Kill horizontal velocity
+}
+
+// Check collision to the LEFT
+if (dx < 0 && hasCollision(cx - 1, cy) && xr <= 0.3) {
+  xr = 0.3;   // Clamp: stop before entering the solid cell
+  dx = 0;     // Kill horizontal velocity
+}
+
+// Cell overflow (after collision check)
+while (xr > 1) { xr--; cx++; }
+while (xr < 0) { xr++; cx--; }
+```
+
+**Why 0.7 and 0.3?** These thresholds represent the entity's collision radius within a cell. An entity centered at `xr = 0.5` with a half-width of 0.3 cells would collide at `xr = 0.7` on the right side and `xr = 0.3` on the left side. Adjust these values based on entity width.
+
+### Y-Axis Collision
+
+Similarly, after applying `dy` to `yr`:
+
+```haxe
+// Apply Y movement
+yr += dy;
+
+// Check collision BELOW (floor)
+if (dy > 0 && hasCollision(cx, cy + 1) && yr >= 1.0) {
+  yr = 1.0;   // Clamp: land on top of the solid cell
+  dy = 0;     // Kill vertical velocity
+}
+
+// Check collision ABOVE (ceiling)
+if (dy < 0 && hasCollision(cx, cy - 1) && yr <= 0.3) {
+  yr = 0.3;   // Clamp: stop before entering ceiling cell
+  dy = 0;     // Kill vertical velocity
+}
+
+// Cell overflow
+while (yr > 1) { yr--; cy++; }
+while (yr < 0) { yr++; cy--; }
+```
+
+For floor collisions, `yr = 1.0` means the entity sits exactly on the bottom edge of its current cell, which is the top edge of the cell below it. This is the natural "standing on ground" position.
+
+### On-Ground Detection
+
+To determine if the entity is standing on solid ground (for jump logic, animations, etc.):
+
+```haxe
+function isOnGround() : Bool {
+  return hasCollision(cx, cy + 1) && yr >= 0.98;
+}
+```
+
+The threshold `0.98` instead of `1.0` allows for minor floating-point imprecision.
+
+### Complete Entity with Collisions
+
+```haxe
+class Entity {
+  var cx : Int = 0;
+  var cy : Int = 0;
+  var xr : Float = 0.5;
+  var yr : Float = 1.0;
+  var dx : Float = 0;
+  var dy : Float = 0;
+  var frictX : Float = 0.82;
+  var frictY : Float = 0.82;
+
+  static inline var GRID = 16;
+  static inline var GRAVITY = 0.05;
+
+  // Collision radius (half-width in cell-ratio units)
+  var collRadius : Float = 0.3;
+
+  function hasCollision(testCx:Int, testCy:Int):Bool {
+    return level.isCollision(testCx, testCy);
+  }
+
+  function isOnGround():Bool {
+    return hasCollision(cx, cy + 1) && yr >= 0.98;
+  }
+
+  public function fixedUpdate() {
+    // --- Gravity ---
+    dy += GRAVITY;
+
+    // --- X Axis ---
+    xr += dx;
+
+    // Right collision
+    if (dx > 0 && hasCollision(cx + 1, cy) && xr >= 1.0 - collRadius) {
+      xr = 1.0 - collRadius;
+      dx = 0;
+    }
+
+    // Left collision
+    if (dx < 0 && hasCollision(cx - 1, cy) && xr <= collRadius) {
+      xr = collRadius;
+      dx = 0;
+    }
+
+    // X cell overflow
+    while (xr > 1) { xr--; cx++; }
+    while (xr < 0) { xr++; cx--; }
+
+    // --- Y Axis ---
+    yr += dy;
+
+    // Floor collision
+    if (dy > 0 && hasCollision(cx, cy + 1) && yr >= 1.0) {
+      yr = 1.0;
+      dy = 0;
+    }
+
+    // Ceiling collision
+    if (dy < 0 && hasCollision(cx, cy - 1) && yr <= collRadius) {
+      yr = collRadius;
+      dy = 0;
+    }
+
+    // Y cell overflow
+    while (yr > 1) { yr--; cy++; }
+    while (yr < 0) { yr++; cy--; }
+
+    // --- Friction ---
+    dx *= frictX;
+    dy *= frictY;
+
+    if (Math.abs(dx) < 0.0005) dx = 0;
+    if (Math.abs(dy) < 0.0005) dy = 0;
+  }
+
+  public function postUpdate() {
+    sprite.x = (cx + xr) * GRID;
+    sprite.y = (cy + yr) * GRID;
+  }
+}
+```
+
+---
+
+## Collision Edge Cases and Solutions
+
+### Diagonal Movement / Corner Clipping
+
+Because collisions are checked per-axis in sequence, an entity moving diagonally into a corner naturally resolves against one axis first. This prevents the entity from getting stuck in corners and eliminates the need for complex diagonal collision logic.
+
+### High-Speed Tunneling
+
+If `dx` or `dy` is large enough to skip an entire cell in one step, the entity could "tunnel" through walls. Solutions:
+
+1. **Cap velocity:** Clamp `dx` and `dy` to a maximum of 0.5 (half a cell per step)
+2. **Subdivide steps:** If velocity exceeds the threshold, run the collision check in smaller increments
+3. **Ray-march the grid:** Check every cell along the movement path
+
+```haxe
+// Simple velocity cap
+if (dx > 0.5) dx = 0.5;
+if (dx < -0.5) dx = -0.5;
+if (dy > 0.5) dy = 0.5;
+if (dy < -0.5) dy = -0.5;
+```
+
+### One-Way Platforms
+
+Platforms the entity can jump up through but land on from above:
+
+```haxe
+// In Y collision, check for one-way platform
+if (dy > 0 && isOneWayPlatform(cx, cy + 1) && yr >= 1.0 && prevYr < 1.0) {
+  yr = 1.0;
+  dy = 0;
+}
+```
+
+Key: Only collide when the entity is moving downward (`dy > 0`) and was previously above the platform (`prevYr < 1.0`).
+
+### Slopes
+
+For basic slope support, instead of a binary collision check, query the slope height at the entity's x-position within the cell:
+
+```haxe
+// Pseudocode for slope collision
+var slopeHeight = getSlopeHeight(cx, cy + 1, xr);
+if (yr >= slopeHeight) {
+  yr = slopeHeight;
+  dy = 0;
+}
+```
+
+---
+
+## Jumping
+
+Jumping is simply a negative `dy` impulse:
+
+```haxe
+function jump() {
+  if (isOnGround()) {
+    dy = -0.5; // Jump impulse (in cell-ratio units)
+  }
+}
+```
+
+Gravity naturally decelerates the upward motion, creating a parabolic arc. To allow variable-height jumps (holding the button longer = higher jump):
+
+```haxe
+// On jump button release, reduce upward velocity
+function onJumpRelease() {
+  if (dy < 0) {
+    dy *= 0.5; // Cut remaining upward velocity
+  }
+}
+```
+
+---
+
+## Coordinate System Diagram
+
+```
+  Cell (cx, cy)           Next Cell (cx+1, cy)
+  +-------------------+   +-------------------+
+  |                   |   |                   |
+  |  xr=0.0    xr=1.0 --> |  xr=0.0           |
+  |                   |   |                   |
+  |         *         |   |                   |
+  |     (xr=0.5,      |   |                   |
+  |      yr=0.5)      |   |                   |
+  |                   |   |                   |
+  +-------------------+   +-------------------+
+  yr=0.0      yr=1.0 = top of cell below
+
+  Pixel position = (cx + xr) * GRID, (cy + yr) * GRID
+```
+
+---
+
+## Update Order Summary
+
+```
+fixedUpdate():
+  1. Apply gravity          dy += GRAVITY
+  2. Apply X velocity       xr += dx
+  3. Check X collisions     Clamp xr, zero dx if colliding
+  4. Handle X cell overflow cx/xr normalization
+  5. Apply Y velocity       yr += dy
+  6. Check Y collisions     Clamp yr, zero dy if colliding
+  7. Handle Y cell overflow cy/yr normalization
+  8. Apply friction         dx *= frictX, dy *= frictY
+  9. Zero out tiny values   Threshold check
+
+postUpdate():
+  1. Sync sprite position   sprite.x/y = pixel coords
+  2. Update animation       Based on state/velocity
+  3. Camera follow          Track entity
+```
+
+---
+
+## Design Advantages
+
+| Feature | Benefit |
+|---------|---------|
+| Grid-based collision | O(1) lookup per check, no broad-phase needed |
+| Dual coordinates | Sub-pixel smooth rendering with integer collision |
+| Per-axis collision | Simple logic, naturally handles corners |
+| Ratio-based velocity | Resolution-independent movement |
+| Friction multiplier | Tunable feel per surface type |
+| Cell overflow while-loops | Handles multi-cell movement safely |