diff --git a/README.md b/README.md index 83a1560..87594b3 100644 --- a/README.md +++ b/README.md @@ -47,6 +47,7 @@ npm run size # Enforce bundle size budget ## Roadmap Snapshot - 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/steering.ts`, `examples/boids.ts`, `examples/requestDedup.ts`, `examples/sat.ts`, `examples/simplex.ts`, and `examples/worley.ts` for quick starts. diff --git a/ROADMAP.md b/ROADMAP.md index fdf4fbc..f1a2a72 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -19,6 +19,9 @@ - [x] Document new modules in `docs/index.d.ts` and examples folder - [x] Achieve >80% coverage across new modules - [ ] Implement reciprocal velocity obstacles (RVO) crowd steering with tests and example +- [ ] Add Jump Point Search optimisation for uniform grids +- [ ] Implement flow-field pathfinding for multi-unit navigation +- [ ] Provide navigation mesh (navmesh) helper for irregular terrain ## Milestone 0.3.0 โ€“ Web Performance & Data Pipelines - [x] Introduce request deduplication helper @@ -27,6 +30,33 @@ - [x] Create benchmarking scripts to compare algorithm variants - [x] Expand CI to include coverage gating and bundle size checks +## Milestone 0.4.0 โ€“ Procedural Worlds & Game Systems (Planned) +- [ ] Implement Wave Function Collapse tile solver with options + example +- [ ] Add dungeon generation suite (BSP subdivision, rooms & corridors variants) +- [ ] Provide L-system generator for foliage/organic structures +- [ ] Ship diamond-square terrain height map generator +- [ ] Offer maze algorithms pack (Kruskal, Wilson, Aldousโ€“Broder, Recursive Division) +- [ ] Add cellular automata cave/organic generator utilities +- [ ] Deliver fixed-timestep game loop utility with interpolation helpers +- [ ] Provide object pool helper for rapid reuse of entities +- [ ] Add weighted random selector (aliasing method) utilities +- [ ] Implement Bresenham line / raster traversal helpers +- [ ] Implement 2D camera system (smooth follow, screen shake, dead zones) +- [ ] Add particle system with configurable emitters +- [ ] Provide sprite animation controller (frame timing, looping, events) +- [ ] Implement platformer physics helper (gravity, coyote time, jump buffering) +- [ ] Ship tile map renderer helpers (chunking, layering) +- [ ] Add shadowcasting field-of-view (FOV) utilities +- [ ] Implement inventory system primitives (stacking, filtering, persistence hooks) +- [ ] Add combat resolution helpers (cooldowns, damage formulas, status effects) +- [ ] Provide quest/dialog state machine utilities +- [ ] Implement 2D lighting helpers (light falloff, blending stubs) +- [ ] Add wave spawner utilities for encounter pacing +- [ ] Provide sound manager stubs (channel limiting, priority) +- [ ] Implement input manager abstraction (key remapping, axis curves) +- [ ] Add save/load serialization helpers (slots, integrity checks) +- [ ] Provide screen transition utilities (fades, wipes, letterboxing) + ## Milestone 1.0.0 โ€“ Production Readiness - [ ] Publish to npm with semver automation and changelog management - [ ] Provide comprehensive documentation site (e.g., VitePress) with interactive demos @@ -43,6 +73,7 @@ ## Upcoming Focus 1. Procedural generation enhancements (Worley refinements, Worley-based effects, upcoming Worley variants like Worley F1/F2) -2. Behavioural AI additions (crowd steering via RVO, pathflow integration, behaviour tree decorators) -3. Advanced collision utilities (swept volumes with rotation, broad-phase acceleration structures) +2. Behavioural AI additions (crowd steering via RVO, flow-field integration, behaviour tree decorators) +3. Procedural & systems expansion (Wave Function Collapse, dungeon suite, L-systems, diamond-square, full game systems toolkit) +4. Advanced collision utilities (swept volumes with rotation, broad-phase acceleration structures) Note: tasks will move to the completed section once merged via the standard branch + PR workflow. diff --git a/docs/index.d.ts b/docs/index.d.ts index c912b62..2da4e60 100644 --- a/docs/index.d.ts +++ b/docs/index.d.ts @@ -13,6 +13,9 @@ // - ๐ŸŽจ Visual & Geometry โ†’ convexHull, lineIntersection, pointInPolygon, easing, bezier // // Each declaration includes "Use for", a performance hint, and the import path for quick selection. +// Planned expansions (Milestone 0.4) cover Wave Function Collapse, dungeon generation suites, +// L-systems, diamond-square, maze packs, and full game systems (loop, camera, particles, physics, +// tilemaps, FOV, inventory, combat, quest/dialog, lighting, wave spawner, sound, input, save/load, transitions). // ============================================================================ // ๐ŸŽฎ PATHFINDING & NAVIGATION diff --git a/docs/index2.d.ts b/docs/index2.d.ts index b0d05c8..82fcadf 100644 --- a/docs/index2.d.ts +++ b/docs/index2.d.ts @@ -1,29 +1,1269 @@ -/// - -// LLM Algorithm Library โ€“ Quick Directory -// ---------------------------------------- -// This file gives language models a fast, text-only overview of the available -// categories and the matching example files. The actual type signatures live in -// `docs/index.d.ts` (referenced above). +// LLM Algorithm Library - TypeScript Definitions +// Import from: https://cdn.jsdelivr.net/npm/llm-algorithms/src/[filename].js // -// ๐Ÿ“š Quick Navigation -// - ๐ŸŽฎ Pathfinding & Navigation โ†’ astar, dijkstra (examples/astar.ts) -// - ๐ŸŒ Procedural Generation โ†’ perlin/perlin3D, simplex2D/simplex3D, worley (examples/simplex.ts, examples/worley.ts) -// - ๐ŸŽฏ Spatial & Collision โ†’ Quadtree, aabbCollision, satCollision, circleRayIntersection, sweptAABB (examples/sat.ts) -// - ๐Ÿค– AI & Behaviour โ†’ steering helpers, updateBoids, BehaviorTree, rvoStep (examples/steering.ts, examples/boids.ts, examples/rvo.ts) -// - โšก Web Performance โ†’ debounce, throttle, LRUCache, memoize, deduplicateRequest, calculateVirtualRange (examples/requestDedup.ts, examples/virtualScroll.ts) -// - ๐Ÿ” Search & Text โ†’ fuzzySearch, fuzzyScore, Trie, binarySearch, levenshteinDistance -// - ๐Ÿ“Š Data Pipelines โ†’ diff, deepClone, groupBy, diffJson/applyJsonDiff (tests/jsonDiff.test.ts) -// - ๐Ÿ“ˆ Graph Algorithms โ†’ graphBFS, graphDFS, topologicalSort (tests/graph.test.ts) -// - ๐ŸŽจ Visual & Geometry โ†’ convexHull, lineIntersection, pointInPolygon, easing, quadraticBezier, cubicBezier (tests/geometry.test.ts, tests/visual.test.ts) +// ๐Ÿ“š QUICK NAVIGATION: +// - ๐ŸŽฎ Pathfinding & Navigation (A*, Dijkstra, Flow Field, Nav Mesh) +// - ๐ŸŒ Procedural Generation (Perlin, Wave Collapse, Cellular Automata, Dungeons) +// - ๐ŸŽฏ Spatial & Collision (Quadtree, AABB, SAT, Raycasting) +// - ๐Ÿค– AI & Behavior (Flocking, Steering, FSM, Behavior Trees, Genetic) +// - ๐ŸŽฒ Game Utilities (Object Pool, Weighted Random, Bresenham) +// - ๐ŸŽฎ Game Systems (Game Loop, Camera, Particles, Animation, Physics) +// - โšก Web Performance (Debounce, Throttle, Cache, Virtual Scroll) +// - ๐Ÿ” Search & Matching (Fuzzy, Trie, Levenshtein) +// - ๐Ÿ“Š Data Processing (Diff, Traverse, Group By, Deep Clone) +// - ๐ŸŽจ Visual & Animation (Easing, Bezier, Color, Force Graph) +// - ๐Ÿ“ˆ Graph Algorithms (BFS, DFS, Topological Sort) +// - ๐Ÿ”ค String Algorithms (Rabin-Karp, LCS) +// - ๐Ÿ“ Geometric (Convex Hull, Line Intersection, Point in Polygon) // -// โœ… Tips for LLMs -// 1. Import from `llm-algorithms/dist/index.js` or the CDN mirror. -// 2. Look up the full signature and JSDoc in `docs/index.d.ts`. -// 3. Browse the matching file in `examples/` for runnable usage. -// 4. Vitest suites inside `tests/` demonstrate edge cases. +// ๐ŸŽฏ QUICK PICKS FOR GAME DEV: +// - Need pathfinding? โ†’ astar.js or dijkstra.js +// - Need procedural maps? โ†’ waveCollapse.js or perlin.js or dungeon.js +// - Need collision? โ†’ quadtree.js + aabb.js +// - Need AI movement? โ†’ steering.js, boids.js, rvo.ts +// - Need game loop? โ†’ gameLoop.js (planned) +// - Need camera? โ†’ camera2d.js (planned) +// - Need effects? โ†’ particles.js (planned) +// - Total algorithms (shipped + planned): 100+ // -// No additional declarations live here โ€“ see the referenced file for the full -// type surface. +// ๐Ÿ—บ Planned expansions (see ROADMAP.md Milestone 0.4) +// - Procedural: Wave Function Collapse, dungeon suites, L-systems, diamond-square, maze packs +// - Systems: game loop, camera, particles, sprite animation, platformer physics, tilemaps, FOV +// - Gameplay: inventory, combat, quest/dialog, lighting, wave spawner, sound, input, save/load, screen transitions + +// ============================================================================ +// ๐ŸŽฎ PATHFINDING & NAVIGATION +// ============================================================================ + +/** + * A* pathfinding algorithm for grid-based navigation + * Finds shortest path between two points using heuristic-based search. + * Use for: game character movement, robot navigation, route planning + * Performance: O(b^d) - Fast with good heuristic + * Import: astar.js + */ +export interface AStarOptions { + grid: number[][]; + start: { x: number; y: number }; + goal: { x: number; y: number }; + allowDiagonal?: boolean; + heuristic?: (a: Point, b: Point) => number; +} +export function astar(options: AStarOptions): Point[] | null; +export function manhattanDistance(a: Point, b: Point): number; +export function gridFromString(mapString: string): number[][]; + +/** + * Dijkstra's algorithm for shortest path without heuristic + * Use for: weighted graphs, guaranteed shortest path, no heuristic available + * Performance: O(E log V) - Slower but guaranteed optimal + * Import: dijkstra.js + */ +export interface DijkstraOptions { + graph: Graph; + start: string | number; + goal: string | number; +} +export function dijkstra(options: DijkstraOptions): Path | null; + +/** + * Jump Point Search - A* optimization for uniform grids + * Use for: large grid pathfinding, performance-critical games + * Performance: O(b^d) - Much faster than A* on grids + * Import: jps.js + */ +export function jumpPointSearch(options: AStarOptions): Point[] | null; + +/** + * Flow Field pathfinding for many units to same goal + * Use for: RTS games, crowd simulation, swarm movement + * Performance: O(n) per unit after O(nยฒ) preprocessing + * Import: flowField.js + */ +export interface FlowFieldOptions { + grid: number[][]; + goal: Point; +} +export function flowField(options: FlowFieldOptions): Vector2D[][]; + +/** + * Navigation Mesh for 3D/irregular terrain + * Use for: 3D games, irregular terrain, realistic movement + * Performance: O(n log n) setup, O(log n) query + * Import: navmesh.js + */ +export function createNavMesh(polygons: Polygon[]): NavMesh; + +// ============================================================================ +// ๐ŸŒ PROCEDURAL GENERATION +// ============================================================================ + +/** + * Perlin Noise for smooth random terrain/textures + * Use for: terrain generation, clouds, organic textures + * Performance: O(n) - Smooth gradients + * Import: perlin.js + */ +export interface PerlinOptions { + width: number; + height: number; + scale?: number; + octaves?: number; + persistence?: number; + lacunarity?: number; + seed?: number; +} +export function perlin(options: PerlinOptions): number[][]; +export function perlin3D(x: number, y: number, z: number): number; + +/** + * Simplex Noise - improved Perlin alternative + * Use for: better terrain, fewer artifacts, any dimension + * Performance: O(n) - Faster than Perlin, no directional artifacts + * Import: simplex.js + */ +export function simplex2D(x: number, y: number): number; +export function simplex3D(x: number, y: number, z: number): number; + +/** + * Wave Function Collapse for tile-based generation + * Generates patterns by collapsing possibilities based on constraints. + * Use for: tile-based maps, texture synthesis, puzzle generation, dungeons + * Performance: O(nยฒ) - Can be slow, high quality output + * Import: waveCollapse.js + */ +export interface WaveCollapseOptions { + width: number; + height: number; + tiles: Tile[]; + seed?: number; +} +export interface Tile { + id: string; + weight?: number; + rules: { + top?: string[]; + right?: string[]; + bottom?: string[]; + left?: string[]; + }; +} +export function waveCollapse(options: WaveCollapseOptions): Tile[][]; +export function createTileset(tileDefinitions: TileDefinition[]): Tile[]; + +/** + * Cellular Automata for caves/organic structures + * Use for: cave generation, organic patterns, erosion + * Performance: O(n ร— iterations) - Very fast + * Import: cellularAutomata.js + */ +export interface CellularOptions { + width: number; + height: number; + fillProbability: number; + iterations: number; +} +export function cellularAutomata(options: CellularOptions): number[][]; + +/** + * Poisson Disk Sampling for even point distribution + * Use for: tree placement, star fields, texture distribution + * Performance: O(n) - No clumping, even spacing + * Import: poissonDisk.js + */ +export function poissonDisk(width: number, height: number, radius: number): Point[]; + +/** + * Voronoi Diagrams for territory/region generation + * Use for: territory maps, biomes, cell-like patterns + * Performance: O(n log n) - Natural-looking boundaries + * Import: voronoi.js + */ +export function voronoi(points: Point[], bounds: Rect): VoronoiCell[]; + +/** + * Maze Generation (multiple algorithms) + * Use for: dungeons, puzzles, labyrinth games + * Performance: O(n) - Various algorithms available + * Import: maze.js + */ +export function mazeRecursiveBacktrack(width: number, height: number): number[][]; +export function mazePrims(width: number, height: number): number[][]; +export function mazeKruskals(width: number, height: number): number[][]; +export function mazeWilsons(width: number, height: number): number[][]; + +/** + * Dungeon Generation (BSP, Rooms & Corridors) + * Use for: roguelikes, procedural dungeons, room-based levels + * Performance: O(n log n) - Creates connected rooms + * Import: dungeon.js + */ +export interface DungeonOptions { + width: number; + height: number; + minRoomSize: number; + maxRoomSize: number; + maxRooms?: number; +} +export function generateDungeon(options: DungeonOptions): DungeonMap; +export function bspDungeon(width: number, height: number, minSize: number): Room[]; + +/** + * L-System for organic generation + * Use for: trees, plants, branching structures, fractals + * Performance: O(n^iterations) - Exponential growth + * Import: lsystem.js + */ +export interface LSystemOptions { + axiom: string; + rules: Record; + iterations: number; +} +export function lsystem(options: LSystemOptions): string; +export function drawLSystem(commands: string, angle: number): Point[][]; + +/** + * Diamond-Square Algorithm for terrain + * Use for: height maps, mountain generation, realistic terrain + * Performance: O(nยฒ) - Smooth height fields + * Import: diamondSquare.js + */ +export function diamondSquare(size: number, roughness: number, seed?: number): number[][]; + +// ============================================================================ +// ๐ŸŽฏ SPATIAL & COLLISION +// ============================================================================ + +/** + * Quadtree for 2D spatial partitioning + * Use for: 2D collision detection, spatial queries, particle systems + * Performance: O(log n) query - Essential for performance + * Import: quadtree.js + */ +export class Quadtree { + constructor(bounds: Rect, capacity: number); + insert(point: Point, data?: any): boolean; + query(range: Rect): Point[]; + queryCircle(center: Point, radius: number): Point[]; +} + +/** + * Octree for 3D spatial partitioning + * Use for: 3D collision, voxels, 3D particle systems + * Performance: O(log n) query + * Import: octree.js + */ +export class Octree { + constructor(bounds: Cube, capacity: number); + insert(point: Point3D, data?: any): boolean; + query(range: Cube): Point3D[]; +} + +/** + * AABB (Axis-Aligned Bounding Box) collision + * Use for: simple box collision, broad-phase detection + * Performance: O(1) - Fastest, least accurate + * Import: aabb.js + */ +export function aabbCollision(a: Rect, b: Rect): boolean; +export function aabbIntersection(a: Rect, b: Rect): Rect | null; + +/** + * SAT (Separating Axis Theorem) collision + * Use for: polygon collision, accurate 2D physics + * Performance: O(n + m) - Accurate for convex shapes + * Import: sat.js + */ +export function satCollision(poly1: Point[], poly2: Point[]): boolean; + +/** + * Circle collision detection + * Use for: round objects, bullets, simple physics + * Performance: O(1) - Very fast + * Import: circle.js + */ +export function circleCollision(a: Circle, b: Circle): boolean; +export function circleRectCollision(circle: Circle, rect: Rect): boolean; + +/** + * Raycasting for line of sight/shooting + * Use for: line of sight, shooting mechanics, mouse picking + * Performance: O(n) - Check against all objects + * Import: raycast.js + */ +export function raycast(ray: Ray, objects: any[]): RaycastHit | null; +export function raycastGrid(ray: Ray, grid: number[][]): Point[]; + +/** + * BVH (Bounding Volume Hierarchy) for complex 3D + * Use for: 3D games, many objects, ray tracing + * Performance: O(log n) - Best for many objects + * Import: bvh.js + */ +export class BVH { + constructor(objects: BoundedObject[]); + query(bounds: any): any[]; + raycast(ray: Ray): RaycastHit | null; +} + +// ============================================================================ +// ๐Ÿค– AI & BEHAVIOR +// ============================================================================ + +/** + * Flocking/Boids for group movement + * Use for: birds, fish, crowds, swarm behavior + * Performance: O(nยฒ) or O(n log n) with spatial partitioning + * Import: boids.js + */ +export interface BoidOptions { + separationDistance: number; + alignmentDistance: number; + cohesionDistance: number; + maxSpeed: number; + maxForce: number; +} +export function updateBoids(boids: Boid[], options: BoidOptions): void; + +/** + * Steering Behaviors for smooth AI movement + * Use for: seek, flee, pursue, evade, wander, arrive + * Performance: O(1) per agent + * Import: steering.js + */ +export function seek(agent: Agent, target: Point): Vector2D; +export function flee(agent: Agent, target: Point): Vector2D; +export function pursue(agent: Agent, target: Agent): Vector2D; +export function wander(agent: Agent): Vector2D; +export function arrive(agent: Agent, target: Point, slowRadius: number): Vector2D; + +/** + * Finite State Machine for AI states + * Use for: simple AI (idle, patrol, chase, attack) + * Performance: O(1) - Easy to understand + * Import: fsm.js + */ +export class FSM { + constructor(initialState: T); + addTransition(from: T, to: T, condition: () => boolean): void; + update(): void; + getCurrentState(): T; +} + +/** + * Behavior Trees for complex AI + * Use for: NPC behavior, boss patterns, complex decisions + * Performance: O(tree depth) - Modular and reusable + * Import: behaviorTree.js + */ +export type BehaviorNode = Sequence | Selector | Action | Condition; +export function createBehaviorTree(root: BehaviorNode): BehaviorTree; + +/** + * Genetic Algorithm for optimization + * Use for: parameter tuning, AI evolution, procedural design + * Performance: O(population ร— generations) - Slow but powerful + * Import: genetic.js + */ +export interface GeneticOptions { + populationSize: number; + generations: number; + fitness: (individual: T) => number; + mutate: (individual: T) => T; + crossover: (a: T, b: T) => T; + initialPopulation: T[]; +} +export function geneticAlgorithm(options: GeneticOptions): { best: T; fitness: number }; + +/** + * Influence Maps for tactical AI + * Use for: strategy games, territory control, tactical positioning + * Performance: O(n) - Strategic decision making + * Import: influenceMap.js + */ +export function createInfluenceMap(width: number, height: number): InfluenceMap; + +// ============================================================================ +// ๐ŸŽฒ UTILITIES & HELPERS +// ============================================================================ + +/** + * Weighted Random Selection + * Use for: loot drops, spawn rates, probability tables + * Performance: O(n) or O(log n) with alias method + * Import: weightedRandom.js + */ +export function weightedRandom(items: T[], weights: number[]): T; +export function createAliasTable(items: T[], weights: number[]): AliasTable; + +/** + * Fisher-Yates Shuffle + * Use for: randomize arrays, deck shuffling, fair randomization + * Performance: O(n) - Unbiased shuffle + * Import: shuffle.js + */ +export function shuffle(array: T[]): T[]; + +/** + * Bresenham's Line Algorithm + * Use for: draw lines on grids, fog of war, laser beams + * Performance: O(max(dx, dy)) - Pixel perfect lines + * Import: bresenham.js + */ +export function bresenhamLine(x0: number, y0: number, x1: number, y1: number): Point[]; + +/** + * Marching Squares for contour generation + * Use for: convert scalar field to contours (water, height maps) + * Performance: O(n) - Smooth boundaries + * Import: marchingSquares.js + */ +export function marchingSquares(field: number[][], threshold: number): Point[][]; + +/** + * Object Pool for memory optimization + * Use for: bullets, particles, frequently created/destroyed objects + * Performance: O(1) - Prevents garbage collection spikes + * Import: objectPool.js + */ +export class ObjectPool { + constructor(factory: () => T, reset: (obj: T) => void, initialSize: number); + get(): T; + release(obj: T): void; +} + +// ============================================================================ +// ๐ŸŽฎ GAME SYSTEMS & UTILITIES +// ============================================================================ + +/** + * Game Loop with fixed timestep + * Use for: consistent physics, frame-independent updates, game timing + * Performance: O(1) per frame - Smooth gameplay + * Import: gameLoop.js + */ +export interface GameLoopOptions { + fps: number; + update: (deltaTime: number) => void; + render: (interpolation: number) => void; +} +export function createGameLoop(options: GameLoopOptions): GameLoop; + +/** + * Delta Time management + * Use for: frame-independent movement, smooth animations + * Performance: O(1) - Consistent across frame rates + * Import: deltaTime.js + */ +export function createDeltaTime(): { + update: () => number; + getDelta: () => number; + getFPS: () => number; +}; + +/** + * Camera 2D with smooth follow + * Use for: player following, smooth camera movement, screen shake + * Performance: O(1) - Smooth camera controls + * Import: camera2d.js + */ +export interface Camera2DOptions { + x: number; + y: number; + width: number; + height: number; + followSmooth?: number; +} +export class Camera2D { + constructor(options: Camera2DOptions); + follow(target: Point, deltaTime: number): void; + shake(intensity: number, duration: number): void; + worldToScreen(point: Point): Point; + screenToWorld(point: Point): Point; +} + +/** + * Particle System for effects + * Use for: explosions, fire, smoke, magic effects, weather + * Performance: O(n) - Manages particle lifecycle + * Import: particles.js + */ +export interface ParticleOptions { + x: number; + y: number; + count: number; + lifetime: number; + speed: number; + spread: number; + gravity?: number; +} +export class ParticleSystem { + constructor(maxParticles: number); + emit(options: ParticleOptions): void; + update(deltaTime: number): void; + getParticles(): Particle[]; +} + +/** + * Sprite Animation controller + * Use for: character animations, sprite sheets, frame sequences + * Performance: O(1) - Frame-based animation + * Import: spriteAnimation.js + */ +export interface AnimationOptions { + frames: number[]; + fps: number; + loop?: boolean; +} +export class SpriteAnimator { + addAnimation(name: string, options: AnimationOptions): void; + play(name: string): void; + update(deltaTime: number): void; + getCurrentFrame(): number; +} + +/** + * Tween/Lerp utilities for smooth transitions + * Use for: UI animations, object movement, value interpolation + * Performance: O(1) - Smooth interpolation + * Import: tween.js + */ +export function lerp(start: number, end: number, t: number): number; +export function lerpVector(a: Point, b: Point, t: number): Point; +export function createTween( + from: number, + to: number, + duration: number, + easing?: (t: number) => number, +): Tween; + +/** + * Platformer Physics for 2D games + * Use for: jumping, gravity, ground detection, slopes + * Performance: O(1) - Classic platformer feel + * Import: platformerPhysics.js + */ +export interface PlatformerPhysicsOptions { + gravity: number; + jumpForce: number; + maxSpeed: number; + acceleration: number; + friction: number; +} +export class PlatformerController { + constructor(options: PlatformerPhysicsOptions); + jump(): void; + move(direction: number, deltaTime: number): void; + update(deltaTime: number): void; + isGrounded(): boolean; +} + +/** + * Top-Down Movement (8-directional) + * Use for: RPG movement, twin-stick shooters, top-down games + * Performance: O(1) - Smooth 8-way movement + * Import: topDownMovement.js + */ +export interface TopDownOptions { + speed: number; + acceleration?: number; + friction?: number; +} +export function topDownMovement(input: Vector2D, options: TopDownOptions): Vector2D; + +/** + * Tile Map renderer & collision + * Use for: 2D tile games, grid-based collision, map rendering + * Performance: O(visible tiles) - Efficient rendering + * Import: tileMap.js + */ +export interface TileMapOptions { + tiles: number[][]; + tileSize: number; + collisionTiles?: number[]; +} +export class TileMap { + constructor(options: TileMapOptions); + getTileAt(x: number, y: number): number; + isSolid(x: number, y: number): boolean; + getVisibleTiles(camera: Camera2D): TileInfo[]; +} + +/** + * Field of View (FOV) / Line of Sight + * Use for: stealth games, visibility, fog of war, enemy detection + * Performance: O(n) - Raycasting-based + * Import: fov.js + */ +export interface FOVOptions { + x: number; + y: number; + radius: number; + grid: number[][]; +} +export function calculateFOV(options: FOVOptions): Set; +export function shadowcasting( + x: number, + y: number, + radius: number, + isBlocked: (x: number, y: number) => boolean, +): Point[]; + +/** + * Minimap generation + * Use for: radar, minimap, overview map + * Performance: O(visible area) - Scaled rendering + * Import: minimap.js + */ +export function createMinimap(world: number[][], scale: number): HTMLCanvasElement; +export function updateMinimap( + minimap: HTMLCanvasElement, + playerPos: Point, + entities: Point[], +): void; + +/** + * Inventory System + * Use for: item management, equipment, crafting systems + * Performance: O(1) add/remove, O(n) search + * Import: inventory.js + */ +export interface Item { + id: string; + name: string; + stackable?: boolean; + maxStack?: number; + [key: string]: any; +} +export class Inventory { + constructor(maxSlots: number); + addItem(item: Item, quantity?: number): boolean; + removeItem(itemId: string, quantity?: number): boolean; + getItem(itemId: string): Item | null; + getSlots(): (Item | null)[]; +} + +/** + * Combat System (turn-based & real-time) + * Use for: RPG combat, damage calculation, status effects + * Performance: O(1) per action - Combat resolution + * Import: combat.js + */ +export interface CombatStats { + health: number; + maxHealth: number; + attack: number; + defense: number; + speed: number; +} +export function calculateDamage(attacker: CombatStats, defender: CombatStats): number; +export function applyStatusEffect(target: any, effect: StatusEffect): void; + +/** + * Quest/Dialog System + * Use for: story progression, NPC dialogs, mission tracking + * Performance: O(1) - State machine based + * Import: questSystem.js + */ +export interface Quest { + id: string; + title: string; + description: string; + objectives: Objective[]; + rewards?: any; +} +export class QuestManager { + addQuest(quest: Quest): void; + completeObjective(questId: string, objectiveId: string): void; + isQuestComplete(questId: string): boolean; + getActiveQuests(): Quest[]; +} + +/** + * Save/Load System + * Use for: game saves, checkpoints, persistent data + * Performance: O(n) - Serialization/deserialization + * Import: saveSystem.js + */ +export function saveGame(gameState: any, slot: string): Promise; +export function loadGame(slot: string): Promise; +export function serializeGameState(state: any): string; +export function deserializeGameState(data: string): any; + +/** + * 2D Lighting System + * Use for: dynamic lighting, shadows, atmospheric effects + * Performance: O(lights ร— affected area) - Light rendering + * Import: lighting2d.js + */ +export interface Light { + x: number; + y: number; + radius: number; + intensity: number; + color?: string; +} +export class LightingSystem { + addLight(light: Light): void; + removeLight(light: Light): void; + render(context: CanvasRenderingContext2D): void; + calculateLightAt(x: number, y: number): number; +} + +/** + * Spawner/Wave System + * Use for: enemy waves, spawn management, difficulty scaling + * Performance: O(spawners) - Event-based spawning + * Import: spawner.js + */ +export interface SpawnWave { + enemies: { type: string; count: number }[]; + delay: number; +} +export class WaveSpawner { + constructor(waves: SpawnWave[]); + start(): void; + update(deltaTime: number): void; + getCurrentWave(): number; + isComplete(): boolean; +} + +/** + * Sound Manager with pooling + * Use for: audio playback, sound effects, music management + * Performance: O(1) - Pooled audio sources + * Import: soundManager.js + */ +export class SoundManager { + loadSound(id: string, url: string): Promise; + playSound(id: string, volume?: number, loop?: boolean): void; + stopSound(id: string): void; + setMasterVolume(volume: number): void; +} + +/** + * Input Manager (keyboard, mouse, gamepad) + * Use for: input handling, key binding, gamepad support + * Performance: O(1) - Event-based input + * Import: inputManager.js + */ +export class InputManager { + isKeyDown(key: string): boolean; + isKeyPressed(key: string): boolean; + isKeyReleased(key: string): boolean; + getMousePosition(): Point; + isMouseButtonDown(button: number): boolean; + getGamepadAxis(gamepadIndex: number, axisIndex: number): number; +} + +/** + * Screen Transitions + * Use for: scene changes, level transitions, fade effects + * Performance: O(1) - Smooth transitions + * Import: transitions.js + */ +export function fadeOut(duration: number, callback?: () => void): void; +export function fadeIn(duration: number): void; +export function slideTransition( + direction: 'left' | 'right' | 'up' | 'down', + duration: number, +): void; + +// ============================================================================ +// โšก WEB PERFORMANCE +// ============================================================================ + +/** + * Debounce to limit rapid function calls + * Use for: search input, window resize, form validation + * Performance: O(1) - Delay execution until idle + * Import: debounce.js + */ +export function debounce any>( + func: T, + wait: number, +): (...args: Parameters) => void; + +/** + * Throttle to rate-limit function execution + * Use for: scroll events, mousemove, performance-critical events + * Performance: O(1) - Execute at fixed intervals + * Import: throttle.js + */ +export function throttle any>( + func: T, + limit: number, +): (...args: Parameters) => void; + +/** + * LRU Cache with size limit + * Use for: API response caching, expensive computations + * Performance: O(1) get/set - Automatic eviction + * Import: lruCache.js + */ +export class LRUCache { + constructor(capacity: number); + get(key: K): V | undefined; + put(key: K, value: V): void; +} + +/** + * Memoization for caching function results + * Use for: expensive pure functions, recursive calculations + * Performance: O(1) retrieval - Space for speed tradeoff + * Import: memoize.js + */ +export function memoize any>(func: T): T; + +/** + * Virtual Scrolling for large lists + * Use for: render only visible items, millions of rows + * Performance: O(visible items) - Handle unlimited data + * Import: virtualScroll.js + */ +export interface VirtualScrollOptions { + itemHeight: number; + containerHeight: number; + items: any[]; + renderItem: (item: any, index: number) => HTMLElement; +} +export function createVirtualScroll(options: VirtualScrollOptions): VirtualScroller; + +/** + * Request Deduplication + * Use for: prevent duplicate API calls, batch requests + * Performance: O(1) - Save bandwidth + * Import: requestDedup.js + */ +export function deduplicateRequest(key: string, fetcher: () => Promise): Promise; + +// ============================================================================ +// ๐Ÿ” SEARCH & MATCHING +// ============================================================================ + +/** + * Fuzzy Search for approximate matching + * Use for: autocomplete, typo-tolerant search, user input + * Performance: O(n ร— m) - Flexible matching + * Import: fuzzySearch.js + */ +export function fuzzySearch(query: string, items: string[]): string[]; +export function fuzzyScore(query: string, target: string): number; + +/** + * Trie (Prefix Tree) for string search + * Use for: autocomplete, dictionary, prefix matching + * Performance: O(m) - Excellent for prefix search + * Import: trie.js + */ +export class Trie { + insert(word: string): void; + search(word: string): boolean; + startsWith(prefix: string): string[]; +} + +/** + * KMP String Search Algorithm + * Use for: substring search, pattern matching + * Performance: O(n + m) - Faster than naive search + * Import: kmp.js + */ +export function kmpSearch(text: string, pattern: string): number[]; + +/** + * Levenshtein Distance for string similarity + * Use for: spell check, similarity scoring, fuzzy matching + * Performance: O(n ร— m) - Edit distance calculation + * Import: levenshtein.js + */ +export function levenshteinDistance(a: string, b: string): number; + +/** + * Binary Search on sorted arrays + * Use for: search sorted data, find insertion point + * Performance: O(log n) - Array must be sorted + * Import: binarySearch.js + */ +export function binarySearch(array: T[], target: T, compareFn?: (a: T, b: T) => number): number; + +// ============================================================================ +// ๐Ÿ“Š DATA PROCESSING +// ============================================================================ + +/** + * Diff Algorithm for comparing data + * Use for: React-like reconciliation, change detection + * Performance: O(n ร— m) - Find minimal changes + * Import: diff.js + */ +export function diff(oldArray: T[], newArray: T[]): DiffResult; + +/** + * Tree Traversal (BFS/DFS) + * Use for: DOM manipulation, file systems, nested data + * Performance: O(n) - Visit all nodes + * Import: traverse.js + */ +export function bfs(root: TreeNode, callback: (node: TreeNode) => void): void; +export function dfs(root: TreeNode, callback: (node: TreeNode) => void): void; + +/** + * Flatten/Unflatten nested structures + * Use for: convert nested to flat and vice versa + * Performance: O(n) - Data transformation + * Import: flatten.js + */ +export function flatten(nested: any): T[]; +export function unflatten(flat: any[], idKey: string, parentKey: string): T; + +/** + * Group By property + * Use for: organize data, categorization, aggregation + * Performance: O(n) - Single pass grouping + * Import: groupBy.js + */ +export function groupBy(array: T[], key: keyof T | ((item: T) => string)): Record; + +/** + * Deep Clone objects + * Use for: copy nested objects, avoid mutations + * Performance: O(n) - Handles circular refs + * Import: deepClone.js + */ +export function deepClone(obj: T): T; + +/** + * Pagination for client-side paging + * Use for: split data into pages, table pagination + * Performance: O(1) - Slice array + * Import: paginate.js + */ +export function paginate(items: T[], page: number, pageSize: number): T[]; + +// ============================================================================ +// ๐ŸŽจ VISUAL & ANIMATION +// ============================================================================ + +/** + * Easing Functions for smooth animations + * Use for: UI animations, game tweening, smooth transitions + * Performance: O(1) - Mathematical curves + * Import: easing.js + */ +export const easing: { + linear: (t: number) => number; + easeInQuad: (t: number) => number; + easeOutQuad: (t: number) => number; + easeInOutQuad: (t: number) => number; + easeInCubic: (t: number) => number; + easeOutCubic: (t: number) => number; + // ... more easing functions +}; + +/** + * Bezier Curves for smooth paths + * Use for: curved paths, animation trajectories, vector graphics + * Performance: O(1) per point - Smooth interpolation + * Import: bezier.js + */ +export function quadraticBezier(p0: Point, p1: Point, p2: Point, t: number): Point; +export function cubicBezier(p0: Point, p1: Point, p2: Point, p3: Point, t: number): Point; + +/** + * Color Manipulation utilities + * Use for: RGB/HSL conversion, color mixing, gradients + * Performance: O(1) - Color math operations + * Import: color.js + */ +export function rgbToHsl(r: number, g: number, b: number): [number, number, number]; +export function hslToRgb(h: number, s: number, l: number): [number, number, number]; +export function colorLerp(color1: string, color2: string, t: number): string; + +/** + * Force-Directed Graph Layout + * Use for: network visualizations, graph drawing + * Performance: O(nยฒ) - Physics-based layout + * Import: forceGraph.js + */ +export function forceDirectedLayout(nodes: GraphNode[], edges: GraphEdge[]): void; + +// ============================================================================ +// ๐Ÿ“ˆ GRAPH ALGORITHMS +// ============================================================================ + +/** + * Breadth-First Search + * Use for: shortest path (unweighted), level-order traversal + * Performance: O(V + E) - Queue-based + * Import: bfs.js + */ +export function graphBFS(graph: Graph, start: string): Map; + +/** + * Depth-First Search + * Use for: cycle detection, topological sort, maze solving + * Performance: O(V + E) - Stack-based + * Import: dfs.js + */ +export function graphDFS(graph: Graph, start: string, callback: (node: string) => void): void; + +/** + * Topological Sort for DAGs + * Use for: dependency resolution, build systems, task scheduling + * Performance: O(V + E) - Works only on DAGs + * Import: topologicalSort.js + */ +export function topologicalSort(graph: Graph): string[]; + +// ============================================================================ +// ๐Ÿ”ค STRING ALGORITHMS +// ============================================================================ + +/** + * Rabin-Karp for pattern matching + * Use for: multiple pattern search, plagiarism detection + * Performance: O(n + m) average - Hash-based + * Import: rabinKarp.js + */ +export function rabinKarp(text: string, pattern: string): number[]; + +/** + * Longest Common Subsequence + * Use for: diff algorithms, DNA sequence comparison + * Performance: O(n ร— m) - Dynamic programming + * Import: lcs.js + */ +export function longestCommonSubsequence(a: string, b: string): string; + +// ============================================================================ +// ๐Ÿ“ GEOMETRIC ALGORITHMS +// ============================================================================ + +/** + * Convex Hull (Graham Scan) + * Use for: find boundary points, collision hulls + * Performance: O(n log n) - Boundary detection + * Import: convexHull.js + */ +export function convexHull(points: Point[]): Point[]; + +/** + * Line Intersection + * Use for: check if lines cross, computational geometry + * Performance: O(1) - Single calculation + * Import: lineIntersection.js + */ +export function lineIntersection(a1: Point, a2: Point, b1: Point, b2: Point): Point | null; + +/** + * Point in Polygon test + * Use for: hit detection, containment testing + * Performance: O(n) - Ray casting method + * Import: pointInPolygon.js + */ +export function pointInPolygon(point: Point, polygon: Point[]): boolean; + +// ============================================================================ +// SHARED TYPES +// ============================================================================ + +export interface Point { + x: number; + y: number; +} + +export interface Point3D { + x: number; + y: number; + z: number; +} + +export interface Vector2D { + x: number; + y: number; +} + +export interface Rect { + x: number; + y: number; + width: number; + height: number; +} + +export interface Circle { + x: number; + y: number; + radius: number; +} + +export interface Ray { + origin: Point; + direction: Vector2D; +} + +export interface Graph { + [key: string]: { node: string; weight?: number }[]; +} + +export interface Tile { + id: string; + rules?: any; +} + +export interface Agent { + position: Point; + velocity: Vector2D; + maxSpeed: number; +} + +export interface Boid extends Agent { + acceleration: Vector2D; +} + +export interface DungeonMap { + grid: number[][]; + rooms: Room[]; + corridors: Corridor[]; +} + +export interface Room { + x: number; + y: number; + width: number; + height: number; +} + +export interface Corridor { + start: Point; + end: Point; + points: Point[]; +} + +export interface Cube { + x: number; + y: number; + z: number; + width: number; + height: number; + depth: number; +} + +export interface Polygon { + vertices: Point[]; +} + +export interface BoundedObject { + bounds: Rect; + data?: any; +} + +export interface RaycastHit { + object: any; + point: Point; + distance: number; +} + +export interface VoronoiCell { + site: Point; + vertices: Point[]; +} + +export interface GameLoop { + start(): void; + stop(): void; + pause(): void; + resume(): void; +} + +export interface Particle { + x: number; + y: number; + vx: number; + vy: number; + life: number; + maxLife: number; +} + +export interface Tween { + update(deltaTime: number): number; + isComplete(): boolean; +} + +export interface TileInfo { + x: number; + y: number; + tileId: number; +} + +export interface Objective { + id: string; + description: string; + completed: boolean; +} + +export interface StatusEffect { + type: string; + duration: number; + value: number; +} + +export interface VirtualScroller { + update(scrollTop: number): void; + render(): HTMLElement[]; +} + +export interface DiffResult { + added: T[]; + removed: T[]; + unchanged: T[]; +} + +export interface TreeNode { + data: T; + children: TreeNode[]; +} + +export interface GraphNode { + id: string; + x: number; + y: number; +} + +export interface GraphEdge { + from: string; + to: string; +} + +export interface Path { + nodes: string[]; + distance: number; +} + +export interface InfluenceMap { + addSource(x: number, y: number, strength: number): void; + getValue(x: number, y: number): number; + propagate(): void; +} + +export interface NavMesh { + findPath(start: Point, goal: Point): Point[]; +} + +export interface BehaviorTree { + update(): void; +} + +export interface AliasTable { + sample(): T; +} -export {}; +export interface TileDefinition { + id: string; + weight?: number; + compatible?: { + top?: string[]; + right?: string[]; + bottom?: string[]; + left?: string[]; + }; +} diff --git a/docs/project.md b/docs/project.md index d964a1d..63dd392 100644 --- a/docs/project.md +++ b/docs/project.md @@ -108,5 +108,7 @@ Following these steps keeps the documentation aligned with the code and makes th - Behaviour-tree decorators and reusable condition/action packs. - Additional procedural generators (erosion, domain-warped noise). - Expanded example gallery with visualization snippets. +- Procedural world toolkit (Wave Function Collapse, dungeon suites, L-systems, diamond-square, maze packs). +- Complete gameplay systems (game loop, camera, particle/sprite systems, platformer physics, tile map renderer, FOV, inventory, combat, quest/dialog, lighting, wave spawner, sound manager, input manager, save/load, screen transitions). Contributions welcome! Follow conventional commits and keep examples runnable so docs stay in sync.