Feature/ray tracing

API.md

@@ -111,6 +111,54 @@ const heading = helpers.findHeading(enemy, player);
 enemy.heading = helpers.rotateTo(heading.angle, enemy.heading, 3);
 ```
 
+## 🗺️ String Tile Maps
+
+Use these helpers to author grid maps as text, then query cells by row/column or
+centered world coordinates.
+
+| Export | Use It For |
+| --- | --- |
+| `parseStringTileMap` | Parse a multiline string into padded tile rows, with optional tile normalization. |
+| `findStringTileMapCell` | Find the first cell containing a tile symbol. |
+| `findStringTileMapCells` | Find all cells containing a tile symbol. |
+| `getStringTileMapTile` | Read one tile by column and row. |
+| `getStringTileMapCenteredPoint` | Convert a column/row into centered `x`/`z` coordinates. |
+| `getStringTileMapCellFromCenteredPoint` | Convert centered `x`/`z` coordinates back into a cell. |
+
+```ts
+const map = parseStringTileMap(
+  `
+########D########
+#      S        #
+#   P      o    #
+#################
+`.trim()
+);
+const spawn = findStringTileMapCell(map, "S");
+```
+
+The isometric dungeon demo uses this editable legend on top of the generic
+string map parser:
+
+| Symbol | Meaning | Role |
+| --- | --- | --- |
+| `space` | Floor | Walkable floor |
+| `#` | Stone wall | Blocking wall |
+| `.` | Floor marker | Walkable floor marker |
+| `C` | Chest | Interactable prop |
+| `D` | Door | Interactable doorway |
+| `P` | Pillar | Blocking prop |
+| `S` | Player spawn | Spawn point |
+| `d` | Stairs down | Interactable stairs |
+| `o` | Light source | Light |
+| `r` | Rubble | Blocking prop |
+| `u` | Stairs up | Interactable stairs |
+| `w` | Water | Walkable slow floor |
+
+Ragged rows can be padded with an internal empty tile such as `_`; the dungeon
+demo treats that as void space outside the playable floor and hides it from the
+editor legend.
+
 ## 🎮 Input Actions
 
 | Export | Use It For |
@@ -325,7 +373,7 @@ achievements = addAchievementProgress(
 
 Achievement helpers are local game-state utilities. Remote leaderboard
 validation is handled by the high-score helpers. See
-`Engine/Systems/New Helpers/Achievements` in Storybook for an interactive
+`Engine/Achievements/Achievements` in Storybook for an interactive
 progress and unlock demo.
 
 ## 🏆 Achievement Notifications
@@ -450,7 +498,7 @@ if (!trusted) {
 ```
 
 Use these helpers alongside your API routes, score storage, used-receipt
-updates, and rate limits. See `Engine/Systems/New Helpers/High Scores` in
+updates, and rate limits. See `Engine/Player Data/High Scores` in
 Storybook for a local leaderboard and validation demo.
 
 ## 🎞️ Sprite Animation
@@ -567,6 +615,48 @@ fillCanvasWithTrail(context, canvas, "#05070a", 0.18);
 drawCanvasLine(context, from, to, "#f6e05e", 2);
 ```
 
+## 💡 Ray Tracing
+
+| Export | Use It For |
+| --- | --- |
+| `createRayTracingRectangle` | Create a clockwise rectangle polygon from top-left coordinates and size. |
+| `createRayTracingBoundsPolygon` | Convert render bounds into a rectangular clipping polygon. |
+| `getRayTracingPolygonSegments` | Convert a polygon into line segments for intersection checks. |
+| `getRayTracingSegments` | Combine bounds and occluder polygons into a segment list. |
+| `traceRay` | Find the nearest segment hit from an origin and angle. |
+| `traceVisibilityPolygon` | Build sorted visibility hits for a light/viewpoint clipped by bounds and occluders. |
+| `traceLightBounces` | Build direct visibility plus capped diffuse bounce layers. |
+
+```ts
+const bounds = { height: canvas.height, width: canvas.width };
+const occluders = [
+  createRayTracingRectangle(120, 90, 64, 48),
+  createRayTracingRectangle(260, 140, 96, 32),
+];
+const visibility = traceVisibilityPolygon({ x: 80, y: 120 }, bounds, occluders);
+
+drawCanvasPolygon(context, visibility, "rgba(255, 220, 120, 0.22)");
+```
+
+```ts
+const layers = traceLightBounces({ x: 80, y: 120 }, bounds, occluders, {
+  bounces: 1,
+  lightColor: "#ffd36f",
+  surfaceColorMix: 0.4,
+});
+```
+
+These helpers only calculate 2D geometry. Games own the final rendering style,
+color blending, gradients, shadow treatment, and interaction model. Bounce
+requests are capped to `0..3` layers for now, and the demo assumes
+low-reflectivity materials with steep attenuation. Bounds and occluders can
+provide `surfaceColor` values so bounced layers inherit some of the material
+color they hit. See
+`Engine/Rendering/Ray Traced Apartment` in Storybook for a Canvas 2D
+lighting demo with draggable furniture, a movable lamp, per-light intensity
+controls, one bounce enabled by default, bounce attenuation tuning, a ray-guide
+toggle, and monochrome TV-static flicker.
+
 ## 🕹️ 2.5D Projection
 
 | Export | Use It For |

README.md

@@ -67,8 +67,11 @@ helper systems could support other arcade-style browser games too.
 - Gravity and lightweight 2D/3D ragdoll helpers for arcade physics effects.
 - Canvas rendering helpers for trails, lines, polygons, hex color parsing, and
   shading.
+- 2D ray tracing helpers for visibility polygons, line-segment ray hits,
+  capped light bounces, and movable occluder lighting demos.
 - 2.5D projection helpers for perspective lanes, isometric tiles, depth loops,
   and pseudo-3D arcade camera effects.
+- String tile-map helpers for authoring board or room layouts as editable text.
 - Arcade motion helpers for first-person camera framing, side-scroller loops,
   jump arcs, and spatial audio pan/depth calculations.
 - Spatial audio math helpers for distance gain, pan, and listener/source mixes.
@@ -311,7 +314,7 @@ platformers.
 
 Achievement helpers keep definition metadata separate from persisted state.
 Games can unlock achievements, increment progress counters, and render status
-lists from the returned data. See the `Engine/Systems/Achievements/Achievements`
+lists from the returned data. See the `Engine/Achievements/Achievements`
 Storybook story for an interactive unlock/progress example.
 
 ### Achievement Notifications
@@ -321,15 +324,15 @@ context. Games provide the achievement text, optional icon frame, viewport, and
 render loop; the renderer owns queue timing, slide/hold/exit animation, text
 wrapping, and placeholder icons.
 
-See the `Engine/Systems/Achievements/Achievement Notifications` Storybook story
+See the `Engine/Achievements/Achievement Notifications` Storybook story
 for a popup queue demo.
 
 ### High Scores
 
 High-score helpers support local score tables and optional remote sync. Games
 provide their own storage key, default scores, API path, settings
 normalizers, and plausibility rules. See the
-`Engine/Systems/Player Data/High Scores` Storybook story for local leaderboard,
+`Engine/Player Data/High Scores` Storybook story for local leaderboard,
 threshold, integrity, and plausibility examples.
 
 Remote leaderboard submissions can use run receipts and integrity payloads.
@@ -345,7 +348,7 @@ providing reusable persistence mechanics. Games provide defaults, optional
 normalization, and a storage key; the store handles localStorage access,
 best-effort writes, reset, subscriptions, and optional DOM change events.
 
-See the `Engine/Systems/Player Data/User Options` Storybook story for a live
+See the `Engine/Player Data/User Options` Storybook story for a live
 options-store example.
 
 ### Runtime Utilities
@@ -370,7 +373,7 @@ normalization math. Use them to offer CRT/VHS/custom settings menus, clamp
 untrusted stored intensities, and layer temporary runtime boosts into effective
 filter settings.
 
-See the `Engine/Systems/Presentation/Display Filters` Storybook story for a
+See the `Engine/Rendering/Display Filters` Storybook story for a
 visual preset demo.
 
 ### Screen Effects
@@ -392,7 +395,7 @@ effects.render(context, { width: canvas.width, height: canvas.height });
 
 The built-in `screen-droplets` effect uses pooled pixel-snapped rectangles for
 rain on a camera lens or visor. See the
-`Engine/Systems/Player Effects/ScreenDroplets` Storybook story for the live
+`Engine/Effects/Player/ScreenDroplets` Storybook story for the live
 demo.
 
 Player effects include screen droplets, fire, frost, low health, poison, shock,
@@ -464,6 +467,27 @@ available to games:
 `fillCanvasWithTrail` accepts any valid CSS color string. Hex-specific helpers
 require 3 or 6 digit hex colors.
 
+### Ray Tracing
+
+Ray tracing helpers calculate 2D visibility polygons from a light or viewpoint
+against rectangular bounds and polygon occluders:
+
+- `createRayTracingRectangle(x, y, width, height)`.
+- `createRayTracingBoundsPolygon(bounds)`.
+- `getRayTracingPolygonSegments(polygon)`.
+- `getRayTracingSegments(bounds, occluders?)`.
+- `traceRay(origin, angle, segments)`.
+- `traceVisibilityPolygon(origin, bounds, occluders?)`.
+- `traceLightBounces(origin, bounds, occluders?, options?)`.
+
+Use them for Canvas 2D lighting, line-of-sight, fog-of-war, stealth vision
+cones, or visibility previews. Bounds and occluders can provide surface colors
+so bounced layers pick up material tint. See the
+`Engine/Rendering/Ray Traced Apartment` Storybook story for
+draggable furniture, a movable lamp, separate light-intensity controls, one
+low-reflectivity bounce enabled by default, a bounce attenuation control, a
+ray-guide toggle, and monochrome TV-static flicker.
+
 ### 2.5D Projection
 
 The `arcade-3d` helpers are renderer-agnostic math functions for arcade-style
@@ -535,10 +559,14 @@ Storybook contains live demos for the engine surface:
 - **Core**: `GameArena`, ticker behavior, viewport scaling, and debug vectors.
 - **Helpers**: math, geometry, object cloning, event binding, collisions,
   rotation, spawning, and 2.5D variants.
-- **Systems**: input actions, local multiplayer, user options, achievements,
-  achievement notifications, high scores, display filters, sprite animation,
-  follow cameras, procedural background stars, player screen effects,
-  environment screen effects, atmospheric effects, and spatial-audio math.
+- **Input**: input actions and local multiplayer input state.
+- **Player Data**: user options and high scores.
+- **Achievements**: achievement progress and notification rendering.
+- **Rendering**: display filters, sprite animation, follow cameras, procedural
+  background stars, and ray-traced apartment lighting.
+- **Effects**: player screen effects, environment screen effects, atmospheric
+  effects, and combined effect scenes.
+- **Physics**: gravity and 2D/3D ragdolls.
 - **Audio**: master controls, effects, music, spatial panning, and global
   playback behavior.
 - **3D**: cube-cluster pickups and modular level pieces.

WHATSNEW.md

@@ -73,6 +73,9 @@
 - Added gravity and lightweight 2D/3D ragdoll helpers for arcade physics
   effects.
 - Added canvas rendering helpers for trails, lines, polygons, and color work.
+- Added 2D ray tracing helpers for visibility polygons, ray/segment hits,
+  rectangular bounds, polygon occluders, surface colors, and capped diffuse
+  bounce layers.
 - Added 2.5D projection helpers for perspective, isometric, and looped-depth
   arcade scenes.
 - Added arcade-motion and spatial-audio math helpers for first-person framing,
@@ -104,21 +107,21 @@
 - Expanded the 2D and 2.5D side-scroller demos with obstacles, ladders,
   platforms, depth-scaled belt actors, and stompable dummy enemies.
 - Added cube-cluster demos for destructible pickups and modular level pieces.
-- Added systems demos for input actions, local multiplayer, sprite animation,
+- Added Storybook demos for input actions, local multiplayer, sprite animation,
   follow cameras, and spatial-audio math.
-- Added systems demos for gravity and 2D/3D ragdoll helpers.
-- Added a systems demo for persisted user option stores.
-- Added a systems demo for CRT/VHS display filter presets.
-- Added a systems demo for achievement notification popups.
-- Added systems demos for achievement progress/unlocks and high-score
+- Added Storybook demos for gravity and 2D/3D ragdoll helpers.
+- Added a Storybook demo for persisted user option stores.
+- Added a Storybook demo for CRT/VHS display filter presets.
+- Added a Storybook demo for achievement notification popups.
+- Added Storybook demos for achievement progress/unlocks and high-score
   leaderboard validation helpers, including Storybook actions and interaction
   checks for their controls.
-- Added Player Effects stories under `Engine/Systems/Player Effects` for screen
+- Added Player Effects stories under `Engine/Effects/Player` for screen
   droplets and player-state fire, frost, poison, low-health, shock, and
   speed-boost overlays.
-- Added Screen Effects stories under `Engine/Systems/Screen Effects` for heat,
+- Added Environment Effects stories under `Engine/Effects/Environment` for heat,
   frost, fire, and underwater environmental overlays.
-- Added Atmospheric Effects stories under `Engine/Systems/Atmospheric Effects`
+- Added Atmospheric Effects stories under `Engine/Effects/Atmospheric`
   for rain, snow, ash, and embers.
 - Replaced flat screen-effect backgrounds with a reusable pixel-art FPS corridor
   demo scene and fixed HUD weapon asset so effects can be evaluated over a
@@ -127,6 +130,10 @@
   position, scale, opacity, and target FPS.
 - Added a Presentation story for procedural stars with forward, reverse,
   strafe, climb, and calm motion presets.
+- Added a Presentation story for a ray-traced top-down apartment with draggable
+  furniture, a movable lamp, per-light intensity controls, blue window light,
+  warm lamp light, one bounce enabled by default, bounce attenuation tuning, a
+  ray-guide toggle, material-tinted bounces, and monochrome TV-static flicker.
 - Added a GitHub Pages workflow that deploys Storybook from `storybook-static`
   without adding Storybook output to the npm package build.
 

package.json

@@ -1,7 +1,7 @@
 {
   "name": "arcade-engine",
   "description": "A small browser arcade-game engine for canvas games.",
-  "version": "4.7.0",
+  "version": "4.10.2",
   "license": "MIT",
   "readmeFilename": "README.md",
   "type": "module",

src/README.md

@@ -78,6 +78,9 @@ Audio must still be started by user gestures when browsers require it.
 - Spawn coordinates along an arc.
 - Radial collision and area-exit checks.
 - Object cloning.
+
+[string-tile-map.ts](string-tile-map.ts) parses text-authored tile maps and
+provides cell lookup helpers for grid, board, and room-style games.
 - Random colors.
 - Event binding and unbinding.
 
@@ -190,7 +193,7 @@ Use it for:
 
 Games keep their concrete option schema, migrations, and validation rules. The
 module is exported from the package root, and the
-`Engine/Systems/Player Data/User Options` Storybook story shows a small
+`Engine/Player Data/User Options` Storybook story shows a small
 settings store.
 
 ## 🧰 Runtime Utilities
@@ -216,7 +219,7 @@ Use it for:
 - Achievement definitions, unlock state, progress counters, and status lists.
 
 The module has no browser dependency and is exported from the package root. The
-`Engine/Systems/Achievements/Achievements` Storybook story shows progress
+`Engine/Achievements/Achievements` Storybook story shows progress
 counters, direct unlocks, status lists, and immutable state updates.
 
 ## 🏆 Achievement Notifications
@@ -252,7 +255,7 @@ Use it for:
 
 Backends can import `arcade-engine/high-scores` for receipt and submission
 validation helpers while keeping route handling, score storage, used-receipt
-updates, and rate limits app-owned. See the `Engine/Systems/Player Data/High Scores`
+updates, and rate limits app-owned. See the `Engine/Player Data/High Scores`
 Storybook story for local leaderboards, default-score merging, thresholds, integrity
 validation, and plausibility feedback.
 
@@ -331,6 +334,23 @@ helpers used by the visual demos:
 `fillCanvasWithTrail` accepts normal CSS colors. The color conversion helpers
 expect 3 or 6 digit hex strings.
 
+## 💡 Ray Tracing
+
+[ray-tracing.ts](ray-tracing.ts) contains renderer-agnostic 2D visibility
+helpers:
+
+- Rectangle and bounds polygon creation.
+- Polygon-to-segment conversion.
+- Nearest ray/segment intersection.
+- Sorted visibility polygon tracing from a light or viewpoint.
+- Capped diffuse bounce layer tracing for simple indirect-light demos.
+- Optional surface colors for material-tinted bounce layers.
+
+Use these helpers for canvas lighting, vision cones, line-of-sight previews,
+fog-of-war shapes, or stealth visibility. The helpers return geometry only;
+games still own gradients, color blending, shadow styling, and interaction.
+Bounce requests are currently capped to `0..3` layers.
+
 ## 🕹️ 2.5D Projection
 
 [arcade-3d.ts](arcade-3d.ts) contains math helpers for pseudo-3D and isometric