Initial Commit

packages/foundation/bitpacker/bitpacker-game/src/interpolation/index.md

@@ -0,0 +1,39 @@
+## Interpolation
+
+**Path:** `src/interpolation/interpolation.ts`  
+**Export:** `GameInterpolator`
+
+### What it does
+
+Advanced interpolation of game state between two points in time. Supports 9 interpolation methods for positions and rotations.
+
+### Methods
+
+| Method | Description |
+|--------|-------------|
+| `LINEAR` | Simple lerp |
+| `CUBIC` | Cubic easing |
+| `HERMITE` | Hermite spline with tension/bias |
+| `CATMULL_ROM` | Catmull-Rom spline |
+| `BEZIER` | Cubic Bezier |
+| `SPRING` | Spring physics |
+| `ELASTIC` | Elastic easing |
+| `BOUNCE` | Bounce easing |
+| `SMOOTHSTEP` | 3t² - 2t³ smoothstep |
+
+### Key API
+
+| Method | Description |
+|--------|-------------|
+| `interpolatePosition(start, end, t, method?)` | Interpolate `Vector3` |
+| `interpolateRotation(start, end, t, method?)` | Interpolate `Rotation` with angle wrapping |
+| `interpolatePlayerState(start, end, t)` | Full player state interpolation |
+| `interpolatePath(points, t, method?)` | Interpolate along a path of points |
+
+### Rotation Handling
+
+Yaw is normalized to `[-180, 180]` and takes the shortest path. Pitch is clamped to `[-90, 90]`.
+
+### Depends on
+
+- `../types.js` — `Vector3`, `Rotation`, `PlayerState`, `InterpolationOptions`