pproenca/dot-skills/fog-of-war-js-ts

dot-skills Fog of War (JavaScript/TypeScript) Best Practices

Performance and correctness guide for fog of war and field-of-view systems in JS/TS games, distilled from the canonical FOV literature (Björn Bergström, Albert Ford, Adam Milazzo), Red Blob Games, rot.js, and the MDN/WebGL rendering APIs. Contains 44 rules across 8 categories, ordered by impact, to guide writing, reviewing, and refactoring visibility code.

When to Apply

Reference these guidelines when:

• Implementing field of view, line of sight, or tile visibility for a grid or continuous map
• Building or refactoring a fog-of-war display (unexplored / explored / visible layers)
• Diagnosing slow fog (recompute every frame), visual artifacts (flicker, light leaks), or memory blowups on large maps
• Scaling visibility to many units (RTS) or to large/streaming worlds
• Choosing how to store and render the visibility/explored state

Rule Categories by Priority

Quick Reference

1. FOV / Visibility Algorithm (CRITICAL)

• `fov-recursive-shadowcasting` - Use recursive shadowcasting, not ray-per-cell FOV
• `fov-symmetric-shadowcasting` - Prefer symmetric shadowcasting for consistent visibility
• `fov-octant-transforms` - Transform octants with a lookup table, not eight loops
• `fov-radius-bounded-scan` - Bound the scan to the sight radius and map edges
• `fov-single-ray-los` - Use a single line-of-sight ray for point-to-point checks
• `fov-dda-continuous` - Traverse continuous space with a DDA grid walk
• `fov-visibility-polygon` - Compute a visibility polygon for smooth 2D fog

2. Update Scheduling & Incremental Recompute (CRITICAL)

• `update-recompute-on-move` - Recompute field of view only when the viewer moves
• `update-dirty-flag` - Track a dirty flag per viewer and a map version stamp
• `update-refcount-visibility` - Count viewers per tile for incremental multi-viewer updates
• `update-delta-not-clear` - Emit visibility deltas instead of clear-all-recompute
• `update-debounce-map-edits` - Batch map edits and recompute affected viewers once
• `update-merge-explored` - Merge visible into explored as you reveal, never rebuild it

3. State Representation & Data Structures (HIGH)

• `state-typed-arrays` - Store fog state in typed arrays, not arrays of objects
• `state-flat-1d-index` - Index a flat buffer with y*width+x, not nested arrays
• `state-three-state-encoding` - Encode the three fog states as bit flags in one byte
• `state-bitset-layers` - Use a bitset for boolean visibility layers
• `state-row-major-iteration` - Iterate row-major to match the buffer's memory layout
• `state-no-string-keys` - Avoid string-keyed maps for per-tile visibility

4. Rendering the Fog Layer (HIGH)

• `render-offscreen-fog-layer` - Render fog to a separate offscreen layer
• `render-dirty-region-only` - Repaint only the dirty fog region
• `render-imagedata-not-fillrect` - Build fog as one ImageData, not per-tile fillRect
• `render-lowres-soft-upscale` - Render soft fog at tile resolution and upscale on the GPU
• `render-webgl-texsubimage` - Upload only the dirty rect of the fog texture in WebGL
• `render-fade-alpha-lerp` - Animate fog reveal by lerping alpha, not recomputing FOV

5. Memory & Allocation (MEDIUM-HIGH)

• `mem-reuse-buffers` - Allocate fog buffers once and reuse them
• `mem-clear-with-fill` - Clear the visible buffer with fill, not reallocation or a loop
• `mem-generation-stamp` - Use a generation stamp to skip the per-frame clear
• `mem-bitpack-explored` - Pack the explored layer into bits for memory and saves
• `mem-no-hot-loop-closures` - Hoist allocations out of the FOV scan loop

6. Multi-Viewer & Map Scaling (MEDIUM)

• `scale-chunk-large-maps` - Chunk large maps and keep only active chunks resident
• `scale-shared-team-visibility` - Share one refcounted visibility buffer per team
• `scale-spatial-partition-edits` - Find edit-affected viewers with a spatial index
• `scale-gameplay-vs-render-culling` - Separate gameplay visibility from on-screen render culling
• `scale-cap-recompute-budget` - Cap FOV recomputes per frame with a time budget

7. Geometry & Hot-Loop Math (MEDIUM)

• `geo-squared-distance` - Compare squared distances to avoid per-cell sqrt
• `geo-avoid-modulo-deindex` - Track x and y directly instead of modulo-deindexing
• `geo-integer-slope-shadows` - Use rational slopes to avoid floating-point drift
• `geo-avoid-trig-in-loop` - Precompute directions instead of calling trig per cell
• `geo-radius-shape-choice` - Choose the radius metric for the shape you want

8. Correctness & Visual Artifacts (LOW-MEDIUM)

• `correct-symmetric-walls` - Light wall tiles consistently to avoid flickering faces
• `correct-corner-peeking` - Handle diagonal wall corners deliberately
• `correct-permissiveness-model` - Pick one permissiveness model and apply it everywhere
• `correct-explored-not-overwritten` - Never let the visible pass overwrite the explored layer

How to Use

Read individual reference files for the full explanation and incorrect/correct code:

• Start with fov- and update- for the two biggest wins: a correct algorithm and recomputing only on change.
• Section definitions - Category structure, impact levels, and the execution-lifecycle ordering.
• Rule template - Template for adding new rules.

Reference Files