feat: add 2d camera system

PROJECT_DESCRIPTION.md

@@ -38,7 +38,8 @@ npm run build
 | Grid pathfinding | `astar`, `dijkstra`, `jumpPointSearch`, `computeFlowField`, `buildNavMesh`, `findNavMeshPath`, `manhattanDistance`, `gridFromString` | `pathfinding/astar.ts`, `pathfinding/dijkstra.ts`, `pathfinding/jumpPointSearch.ts`, `pathfinding/flowField.ts`, `pathfinding/navMesh.ts` | `examples/astar.ts`, `examples/flowField.ts`, `examples/navMesh.ts` |
 | Procedural textures & terrain | `perlin`, `perlin3D`, `simplex2D`, `simplex3D`, `worley`, `worleySample`, `waveFunctionCollapse`, `cellularAutomataCave`, `poissonDiskSampling`, `computeVoronoiDiagram`, `diamondSquare`, `generateLSystem`, `generateBspDungeon`, `generateRecursiveMaze`, `generatePrimMaze`, `generateKruskalMaze`, `generateWilsonMaze`, `generateAldousBroderMaze`, `generateRecursiveDivisionMaze` | `procedural/*.ts` | `examples/simplex.ts`, `examples/worley.ts`, `examples/waveFunctionCollapse.ts`, `examples/cellularAutomata.ts`, `examples/poissonDisk.ts`, `examples/voronoi.ts`, `examples/diamondSquare.ts`, `examples/lSystem.ts`, `examples/dungeonBsp.ts`, `examples/mazeRecursive.ts`, `examples/mazePrim.ts`, `examples/mazeKruskal.ts`, `examples/mazeWilson.ts`, `examples/mazeAldous.ts`, `examples/mazeDivision.ts` |
 | Spatial queries & collision | `Quadtree`, `aabbCollision`, `aabbIntersection`, `satCollision`, `circleRayIntersection`, `sweptAABB` | `spatial/*.ts` | `examples/sat.ts` |
-| Web performance & UI throttling | `debounce`, `throttle`, `LRUCache`, `memoize`, `deduplicateRequest`, `clearRequestDedup`, `calculateVirtualRange`, `createWeightedAliasSampler`, `createObjectPool`, `fisherYatesShuffle`, `createFixedTimestepLoop` | `util/*.ts` | `examples/requestDedup.ts`, `examples/virtualScroll.ts`, `examples/weightedAlias.ts`, `examples/objectPool.ts`, `examples/fisherYates.ts`, `examples/fixedTimestep.ts` |
+| Web performance & UI throttling | `debounce`, `throttle`, `LRUCache`, `memoize`, `deduplicateRequest`, `clearRequestDedup`, `calculateVirtualRange`, `createWeightedAliasSampler`, `createObjectPool`, `fisherYatesShuffle` | `util/*.ts` | `examples/requestDedup.ts`, `examples/virtualScroll.ts`, `examples/weightedAlias.ts`, `examples/objectPool.ts`, `examples/fisherYates.ts` |
+| Gameplay systems | `createDeltaTimeManager`, `createFixedTimestepLoop`, `createCamera2D` | `util/deltaTime.ts`, `util/fixedTimestep.ts`, `gameplay/camera2D.ts` | `examples/deltaTime.ts`, `examples/fixedTimestep.ts`, `examples/camera2D.ts` |
 | Text & search | `fuzzySearch`, `fuzzyScore`, `Trie`, `binarySearch`, `levenshteinDistance` | `search/*.ts` | `examples/search.ts` |
 | Data transforms & diffing | `diff`, `deepClone`, `groupBy`, `diffJson`, `applyJsonDiff` | `data/*.ts` | `examples/jsonDiff.ts` |
 | Graph traversal | `graphBFS`, `graphDFS`, `topologicalSort` | `graph/traversal.ts` | `examples/graph.ts` |
@@ -60,6 +61,7 @@ llm-algorithms/
 │   ├── ai/
 │   ├── data/
 │   ├── geometry/
+│   ├── gameplay/
 │   ├── graph/
 │   ├── pathfinding/
 │   ├── procedural/
@@ -91,11 +93,12 @@ Consistency between runtime code, documentation, and TypeScript declarations kee
 - **Pathfinding:** A*, Dijkstra, Jump Point Search, flow field integration, Manhattan heuristic, grid string parser.
 - **Procedural:** 2D/3D Perlin, Worley noise, Wave Function Collapse tile synthesis.
 - **Spatial:** Quadtree, AABB helpers, SAT convex polygon collision.
-- **Performance utilities:** Debounce, throttle, LRU cache, memoize, request deduplication, virtual scrolling.
+- **Performance utilities:** Debounce, throttle, LRU cache, memoize, request deduplication, virtual scrolling, weighted alias sampling, object pooling, Fisher–Yates shuffle.
+- **Gameplay systems:** Delta-time manager, fixed timestep loop, 2D camera with smoothing and shake.
 - **Search:** Fuzzy search + scoring, Trie-based autocomplete, binary search, Levenshtein distance.
 - **Data tools:** Diff operations (LCS), deep clone, groupBy, JSON diff/patch helpers.
 - **Graph:** BFS distance map, DFS traversal, topological sort.
-- **Geometry & visuals:** Convex hull, line intersection, point-in-polygon, easing presets, quadratic/cubic Bezier evaluation.
+- **Geometry & visuals:** Convex hull, line intersection, point-in-polygon, Bresenham line rasterisation, easing presets, quadratic/cubic Bezier evaluation.
 - **AI behaviours:** Steering behaviours (seek, flee, arrive, pursue, wander), boids, behaviour trees, RVO crowd steering.
 
 ---

README.md

@@ -28,7 +28,8 @@ CDN usage:
 | Procedural generation | `perlin`, `perlin3D`, `simplex2D`, `simplex3D`, `worley`, `worleySample`, `waveFunctionCollapse`, `cellularAutomataCave`, `poissonDiskSampling`, `computeVoronoiDiagram`, `diamondSquare`, `generateLSystem`, `generateBspDungeon`, `generateRecursiveMaze`, `generatePrimMaze`, `generateKruskalMaze`, `generateWilsonMaze`, `generateAldousBroderMaze`, `generateRecursiveDivisionMaze` | `procedural/*.ts` | `examples/simplex.ts`, `examples/worley.ts`, `examples/waveFunctionCollapse.ts`, `examples/cellularAutomata.ts`, `examples/poissonDisk.ts`, `examples/voronoi.ts`, `examples/diamondSquare.ts`, `examples/lSystem.ts`, `examples/dungeonBsp.ts`, `examples/mazeRecursive.ts`, `examples/mazePrim.ts`, `examples/mazeKruskal.ts`, `examples/mazeWilson.ts`, `examples/mazeAldous.ts`, `examples/mazeDivision.ts` |
 | Spatial queries & collision | `Quadtree`, `aabbCollision`, `aabbIntersection`, `satCollision`, `circleRayIntersection`, `sweptAABB` | `spatial/*.ts` | `examples/sat.ts` |
 | AI behaviours & crowds | `seek`, `flee`, `arrive`, `pursue`, `wander`, `updateBoids`, `BehaviorTree`, `rvoStep` | `ai/steering.ts`, `ai/boids.ts`, `ai/behaviorTree.ts`, `ai/rvo.ts` | `examples/steering.ts`, `examples/boids.ts`, `examples/rvo.ts` |
-| Web performance & UI | `debounce`, `throttle`, `LRUCache`, `memoize`, `deduplicateRequest`, `clearRequestDedup`, `calculateVirtualRange`, `createWeightedAliasSampler`, `createObjectPool`, `createDeltaTimeManager`, `createFixedTimestepLoop`, `fisherYatesShuffle` | `util/*.ts` | `examples/requestDedup.ts`, `examples/virtualScroll.ts`, `examples/weightedAlias.ts`, `examples/objectPool.ts`, `examples/deltaTime.ts`, `examples/fixedTimestep.ts`, `examples/fisherYates.ts` |
+| Web performance & UI | `debounce`, `throttle`, `LRUCache`, `memoize`, `deduplicateRequest`, `clearRequestDedup`, `calculateVirtualRange`, `createWeightedAliasSampler`, `createObjectPool`, `fisherYatesShuffle` | `util/*.ts` | `examples/requestDedup.ts`, `examples/virtualScroll.ts`, `examples/weightedAlias.ts`, `examples/objectPool.ts`, `examples/fisherYates.ts` |
+| Gameplay systems | `createDeltaTimeManager`, `createFixedTimestepLoop`, `createCamera2D` | `util/deltaTime.ts`, `util/fixedTimestep.ts`, `gameplay/camera2D.ts` | `examples/deltaTime.ts`, `examples/fixedTimestep.ts`, `examples/camera2D.ts` |
 | Search & text | `fuzzySearch`, `fuzzyScore`, `Trie`, `binarySearch`, `levenshteinDistance` | `search/*.ts` | `examples/search.ts` |
 | Data & diff pipelines | `diff`, `deepClone`, `groupBy`, `diffJson`, `applyJsonDiff` | `data/*.ts` | `examples/jsonDiff.ts` |
 | Graph algorithms | `graphBFS`, `graphDFS`, `topologicalSort` | `graph/traversal.ts` | `examples/graph.ts` |
@@ -52,7 +53,7 @@ npm run size        # Enforce bundle size budget
 - Milestone 0.2 next targets crowd-flow integrations (RVO + flow fields) and behaviour-tree decorators for richer AI control.
 - Milestone 0.4 plans a procedural + gameplay systems toolkit (Wave Function Collapse, dungeon suite, L-systems, game loop, camera, particles, inventory, combat, save/load, and more).
 
-Examples live under `examples/` and can be executed with `tsx`/`ts-node` or compiled for the browser. See `examples/astar.ts`, `examples/flowField.ts`, `examples/navMesh.ts`, `examples/cellularAutomata.ts`, `examples/poissonDisk.ts`, `examples/voronoi.ts`, `examples/diamondSquare.ts`, `examples/lSystem.ts`, `examples/dungeonBsp.ts`, `examples/mazeRecursive.ts`, `examples/mazePrim.ts`, `examples/mazeKruskal.ts`, `examples/mazeWilson.ts`, `examples/mazeAldous.ts`, `examples/mazeDivision.ts`, `examples/steering.ts`, `examples/boids.ts`, `examples/requestDedup.ts`, `examples/search.ts`, `examples/graph.ts`, `examples/geometry.ts`, `examples/visual.ts`, `examples/sat.ts`, `examples/simplex.ts`, and `examples/worley.ts` for quick starts. The `examples` registry exported from `src/index.ts` provides a typed index you can traverse programmatically.
+Examples live under `examples/` and can be executed with `tsx`/`ts-node` or compiled for the browser. See `examples/astar.ts`, `examples/flowField.ts`, `examples/navMesh.ts`, `examples/cellularAutomata.ts`, `examples/poissonDisk.ts`, `examples/voronoi.ts`, `examples/diamondSquare.ts`, `examples/lSystem.ts`, `examples/dungeonBsp.ts`, `examples/mazeRecursive.ts`, `examples/mazePrim.ts`, `examples/mazeKruskal.ts`, `examples/mazeWilson.ts`, `examples/mazeAldous.ts`, `examples/mazeDivision.ts`, `examples/steering.ts`, `examples/boids.ts`, `examples/requestDedup.ts`, `examples/deltaTime.ts`, `examples/fixedTimestep.ts`, `examples/camera2D.ts`, `examples/search.ts`, `examples/graph.ts`, `examples/geometry.ts`, `examples/bresenham.ts`, `examples/visual.ts`, `examples/sat.ts`, `examples/simplex.ts`, and `examples/worley.ts` for quick starts. The `examples` registry exported from `src/index.ts` provides a typed index you can traverse programmatically.
 
 ## Contributing
 1. Fork the repository.

ROADMAP.md

@@ -51,7 +51,7 @@
   - [x] Fisher–Yates shuffle implementation
   - [x] Bresenham line / raster traversal helpers
 - Real-time systems:
-  - [ ] 2D camera system (smooth follow, dead zones, screen shake)
+  - [x] 2D camera system (smooth follow, dead zones, screen shake)
   - [ ] Particle system with configurable emitters
   - [ ] Sprite animation controller (frame timing, events)
   - [ ] Tween/lerp utility for smooth interpolation

docs/index.d.ts

@@ -919,6 +919,94 @@ export interface FixedTimestepLoop {
  */
 export function createFixedTimestepLoop(options: FixedTimestepOptions): FixedTimestepLoop;
 
+// ============================================================================
+// 🕹️ GAMEPLAY SYSTEMS
+// ============================================================================
+
+/**
+ * Camera bounds limiting camera travel.
+ * Use for: constraining view to world dimensions.
+ * Import: gameplay/camera2D.ts
+ */
+export interface CameraBounds {
+  minX: number;
+  maxX: number;
+  minY: number;
+  maxY: number;
+}
+
+/**
+ * Deadzone rectangle keeping targets centred only when they exit the buffer.
+ * Use for: platformer cameras, cinematic offsets.
+ * Import: gameplay/camera2D.ts
+ */
+export interface CameraDeadzone {
+  width: number;
+  height: number;
+}
+
+/**
+ * Camera shake configuration.
+ * Use for: explosions, damage feedback, cinematic moments.
+ * Import: gameplay/camera2D.ts
+ */
+export interface CameraShakeOptions {
+  duration?: number;
+  magnitude: number;
+  frequency?: number;
+}
+
+/**
+ * 2D camera configuration options.
+ * Use for: smooth follow cameras with bounds and dead zones.
+ * Import: gameplay/camera2D.ts
+ */
+export interface Camera2DOptions {
+  viewportWidth: number;
+  viewportHeight: number;
+  position?: Point;
+  bounds?: CameraBounds;
+  deadzone?: CameraDeadzone;
+  smoothing?: number;
+  random?: () => number;
+}
+
+/**
+ * Camera update input.
+ * Use for: advancing the camera each frame with delta time and target.
+ * Import: gameplay/camera2D.ts
+ */
+export interface CameraUpdateOptions {
+  target: Point;
+  delta: number;
+}
+
+/**
+ * 2D camera runtime API.
+ * Use for: retrieving view rects, configuring behaviour, triggering shake.
+ * Import: gameplay/camera2D.ts
+ */
+export interface Camera2D {
+  update(options: CameraUpdateOptions): Rect;
+  getView(): Rect;
+  getPosition(): Point;
+  getCenter(): Point;
+  setBounds(bounds?: CameraBounds): void;
+  setDeadzone(deadzone?: CameraDeadzone): void;
+  setSmoothing(value: number): void;
+  applyShake(options: CameraShakeOptions): void;
+  isShaking(): boolean;
+  reset(position?: Point): void;
+}
+
+/**
+ * Creates a 2D camera with smoothing, dead zones, and screen shake support.
+ * Use for: side-scrollers, top-down games, cinematic sequences.
+ * Performance: O(1) per update.
+ * Import: gameplay/camera2D.ts
+ */
+export function createCamera2D(options: Camera2DOptions): Camera2D;
+
 /**
  * Least recently used cache.
  * Use for: memoizing responses, data loaders, pagination caches.

examples/camera2D.ts

@@ -0,0 +1,22 @@
+import { createCamera2D } from '../src/index.js';
+
+const camera = createCamera2D({
+  viewportWidth: 16,
+  viewportHeight: 9,
+  deadzone: { width: 4, height: 2 },
+  smoothing: 0.2,
+});
+
+let time = 0;
+const target = { x: 0, y: 0 };
+
+for (let i = 0; i < 5; i += 1) {
+  time += 1 / 60;
+  target.x = Math.cos(time) * 20;
+  target.y = Math.sin(time) * 5;
+  const view = camera.update({ target, delta: 1 / 60 });
+  console.log(`frame ${i}:`, view);
+}
+
+camera.applyShake({ magnitude: 1, duration: 0.3 });
+console.log('shake:', camera.update({ target, delta: 1 / 60 }));