http://github.com/dylang/node-rsssite-lib/media/favicon.pngWebpage HTML Export plugin for ObsidianSun, 23 Nov 2025 21:11:56 GMTSun, 23 Nov 2025 21:11:56 GMT60Movement System
Reactions: Timer type, timer value, type transformations - see cross-referenceReaction System
Rendering: All data for visual representation - see cross-referenceRendering ]]>architecture/general/shader-data-layout.htmlarchitecture/general/shader-data-layout.mdWed, 12 Nov 2025 05:27:37 GMTSystem Overview - Complete architectural design and module relationships
Data Flow - Frame execution pipeline and module communication ⚠️ OUTDATED
Performance Strategy - Optimization approaches and technical constraints
Technical Decisions - Design choices and rationale
Implementation Guide - Step-by-step implementation approach ⚠️ STUB
Determinism - Fixed-point arithmetic and cross-platform consistency
Variable Timing System - Time slice scheduling and player action management ⚠️ PROPOSED
State Management - Snapshots, rollback, and multiplayer synchronization ⚠️ STUB
Ghost Simulation - Predictive action visualization system ⚠️ PROPOSED Modular Design: Modules with focused responsibilitiesWebGPU Processing: Physics, reactions, and rendering use GPU computeDeterministic Requirements: Identical inputs must produce identical outputs for PvP through simultaneous single-read/single-write GPU passesActive Region System: Process only chunks with changing tiles ⚠️ NOT IMPLEMENTED: Active region optimization was decided against⚠️ Unsolved Issues Requiring Design Work: Frame rate coordination between physics, reactions, and rendering systems GPU thread execution determinism guarantees (current approach: simultaneous read/write passes) Specific rule compilation pipeline implementation ]]>architecture/general/general.htmlarchitecture/general/general.mdWed, 12 Nov 2025 05:27:19 GMTMovement - Hexagonal grid, sub-grid positioning, velocity, and mass
Cohesion - Gap-closing attraction forces
Collision - Overlap repulsion forces
Object Merging - How nearby objects combine into single objects
Reactions - Type transformations from merging and environmental patterns
Pipeline Passes - GPU execution coordination
Spell Integration - How spells affect physics layer
cross-referenceDeterminism - Fixed-point arithmetic and cross-platform consistency ensuring identical physics results everywhereHexagonal Grid: Corner-to-corner cell size d ensures no two objects occupy the same cell, even during movement.Direct Force Resolution: Forces applied continuously while objects overlap - no iterative convergence.Speed Limits: Maximum ~9.69 cells/second at 60fps, with typical gameplay 2-6 cells/second.Three Layers: Ground, Object, and Air layers for different entity types.
Spell System: Spells apply forces and trigger tile transformations - see Spell Integration.Renderer: Provides sub-grid positions, velocities, and timer states for smooth visuals.]]>architecture/systems/physics/physics.htmlarchitecture/systems/physics/physics.mdWed, 12 Nov 2025 05:26:49 GMTElement System - 26 elements in cube/octahedron structure
Element Effects - What each element does (forces, transformations, passives)
Mana System - 6 flower types with recharge and conversion
Spells and Runes - Casting interface and rune lifecycle
Deck Building - Deck rules and pre-match construction
Customization - Curse system and build options
CPU Architecture - Outdated, system now GPU-accelerated
cross-referenceSpell Integration - How spells affect physics layer
cross-referenceCore Engine - Texture management and layer coordination
Physics Engine: Spells apply forces and trigger tile transformations - see cross-referenceSpell Integration.Core Engine: Manages spell layer texture for GPU processing.UI System: Displays casting slots/pools, mana flower availability, targeting overlay, and deck builder interface.Documented: Element system (26 elements, cancellation rules) Mana system (6 flowers, recharge, conversion) Casting interface (slot/pool, actions, cooldown) Rune lifecycle (placement, delay, trigger, combination) Deck building rules (minimum size, singleton, reshuffle) Needs Design: Specific spell shape primitives Void rune effects Single element rune additional effects Curse system mechanics Spell acquisition/progression system Line of sight obstruction rules Number of casting slots/pools
Entry Point: Start with Element System to understand the foundational magic structure.]]>architecture/systems/spells/spells.htmlarchitecture/systems/spells/spells.mdWed, 12 Nov 2025 05:26:24 GMTMana System) Triggers directional targeting mode Slot becomes empty after cast Pools unchanged 2. Load Spell (pool → empty slot): Player selects spell from any pool Chosen spell moves to clicked slot
All pools refill sequentially from deck (see cross-referenceDeck Building) No mana cost 3. Refresh Pools: Manually replace all pool spells with new draws from deck Triggers action cooldown Flowers do NOT recharge during refresh cooldown (unique penalty) Universal Cooldown: Single shared cooldown applies to all three actionsMovement: Not affected by action cooldownHold-to-Cast Queueing: Hold mouse on filled slot during cooldown to queue cast for immediate execution when readyActivation: After clicking cast, enter targeting modeInput: Player clicks direction and distance from avatarPlacement: Spell shape centered on clicked locationRange Limits: Each spell has maximum range from casterObstruction: ⚠️ NEEDS DESIGN - Line of sight checks TBDDesign: Abstract geometric primitives (circles, rectangles, lines, etc.) evaluated at runtimeNot Textures: Mathematical definitions, not pre-rendered imagesEvaluation: GPU compute shaders evaluate shape membership per-pixelPrimitives: ⚠️ NEEDS SPECIFICATION - Specific primitive set TBD through spell design processShape Components: Position (relative to spell center) Rotation and scale
Element type (from cross-referenceElement System) Force vector Delay value Placement: Spell casting writes runes to rune layer via GPU Delay Countdown: GPU shader decrements delay counter each frame Trigger + Removal: Simultaneous - apply effects and remove rune when delay reaches zero Combination: Multiple runes on same pixel combine before triggering
Element Type: One of 26 elements (see cross-referenceElement System)
Force Vector: Applied to physics layer when triggered (see cross-referenceSpell Integration)Delay Counter: Frame-based countdownStorage: Per-pixel on dedicated rune layer textureNote: ⚠️ Runes are being replaced by spell shapes - this document needs updating to reflect current architecture.Timing: Runes combine when multiple exist on same pixel
Element Rules: Uses element system cancellation rules (see cross-referenceElement System)Force Combination: Vector addition of all force componentsDelay Resolution: Combined rune uses minimum delay of componentsTrigger Timing: Combined rune triggers when shortest delay expiresDelay System: 16-bit looping time counter, runes store target trigger timeShape Evaluation: Compute shaders evaluate abstract primitives per-pixel during spell placementElement Combination: Shader-based component-level cancellation during rune combinationCleanup: Separate shader pass removes triggered runesDeterminism: Fixed-point precision, order-independent combination results]]>architecture/systems/spells/spells-and-runes.htmlarchitecture/systems/spells/spells-and-runes.mdWed, 12 Nov 2025 05:26:08 GMTElement Effects - What each element does (forces, transformations, passive effects)
cross-referenceMana System - Flower types match base elements, spell costs require specific combinations
cross-referenceSpells and Runes - Element combinations computed in GPU shaders during rune placementAvailability: All 26 elements accessible from game start. No progression gate on element types.]]>architecture/systems/spells/element-system.htmlarchitecture/systems/spells/element-system.mdWed, 12 Nov 2025 05:25:47 GMTElement System for structure and cancellation mechanics.Properties: No directional component, neutral/null element.Force Effects: ⚠️ TBD through spell system design.Transformation Effects: ⚠️ TBD through spell system design.Properties: Pure directional elements along three axes (hot/cold, kinetic/static, light/dark).Force Effects: ⚠️ TBD - May provide basic force application.Transformation Effects: ⚠️ TBD - Single-element transformation capabilities.Properties: Combination of two axis components (e.g., hot+kinetic, cold+light).Primary Duty: Most double-element spells provide BOTH force application AND tile transformations.Force Types: ⚠️ NEEDS SPECIFICATION - Impulse vs velocity-set per element.Transformation Effects: ⚠️ NEEDS SPECIFICATION - Tile type changes triggered by spell.Properties: Combination of all three axis components.Primary Duty: Passive modifications to physics behavior.⚠️ TODO: Triple-element spells will provide passive modifications to reactions and forces for their duration.Design Intent: Global or area-of-effect modifiers to game rules while spell is active.Examples (speculative): Modify force strengths, alter reaction rates, change timer behaviors.Properties: Absence of all axes, neutral element.Special Role: ⚠️ TBD - May have unique mechanics or serve as cancellation result.Method: Add velocity delta to current object velocity.Application: Δv applied once when spell contacts object.Use Cases: Push, pull, explosion effects.Elements: ⚠️ NEEDS SPECIFICATION - Which elements use impulse method?Method: Directly replace object velocity with spell-specified value.Application: Overrides current velocity entirely.Use Cases: Wind, flow, directional movement effects.Elements: ⚠️ NEEDS SPECIFICATION - Which elements use velocity-set method?⚠️ NEEDS DISCUSSION: Do spell forces ignore mass (magical effects) or respect mass (physical forces)?Impact: Determines if heavy objects respond same as light objects to spells.Trigger: When double-element spell activates on a tile.Process: Tile type changes based on spell elements and current tile type.Rule Source: Transformation rules defined per element combination.⚠️ NEEDS SPECIFICATION: Complete mapping of element combinations to tile transformations.Examples (speculative): Fire element: Transform wood → burning wood → ash Ice element: Transform water → ice Earth element: Create/modify terrain Coordination: Spell transformations may interact with reaction system environmental effects.Rule Separation: Spell-triggered transformations separate from physics-driven reactions.
See cross-referenceSpell Integration and cross-referenceReactions.⚠️ TODO: Design passive modification system for triple-element spells.Duration: Modifications active while spell is present.Scope: May affect global rules or localized area.Potential Effects: Modify force strengths (amplify/dampen collision, cohesion, spell forces) Alter reaction rates (speed up/slow down environmental reactions) Change timer behaviors (faster burning, slower freezing, etc.) Modify mass response (objects lighter/heavier under effect) ⚠️ NEEDS COMPLETION: Catalog all 26 elements with specific effects.The 26 elements are organized as: 1 Core (null) 6 Single-axis (hot, cold, kinetic, static, light, dark) 12 Double-axis (all pairwise combinations of opposite axes) 6 Triple-axis (hot/cold + kinetic/static + light/dark combinations) 1 Null (three cancellations)
See Element System for complete structure and cancellation rules.Goal: Each element should feel unique and have clear gameplay identity.Balance: Elements should be roughly balanced in power/utility.Synergy: Element combinations should create interesting strategic choices.Tuning: Force strengths will require gameplay testing and iteration.Configuration: Expose force values as tunable parameters.Variation: Different elements may have different force strengths for balance.Clarity: Players should understand what each element does to tiles.Consistency: Similar elements should have thematically consistent effects.Balance: Transformation effects balanced against force effects for double-elements.
Element System - Structure and cancellation rules
Spells and Runes - How elements are cast and combined
cross-referenceSpell Integration - How elements affect physics layer
cross-referenceReactions - Interaction with reaction systemCurrent State: Structure defined, specific effects TBD through design process.Next Steps: Define force type (impulse/velocity-set) for each element Specify force magnitudes for gameplay testing Design tile transformation rules for double-elements Design passive modification system for triple-elements Iterate through playtesting and balance ]]>architecture/systems/spells/element-effects.htmlarchitecture/systems/spells/element-effects.mdWed, 12 Nov 2025 05:25:31 GMTSpell Integration.
When: Objects merge during physics overlap passes when distance < d (see Object Merging).Lookup: Hashmap mapping object type pairs to new types: (type_a, type_b) -> new_typeMultiple Objects: When 3+ objects merge, only pairs are considered (see todo for preventing triple merges).Timer Reset: All transformations reset the object's timer.Source: Object merging (physics-driven), NOT spell-triggered transformations.When: Every physics frame during "Apply Forces + Move" pass.Gather-Based: Each object checks its two-layer hex neighborhood for nearby types.Lookup: Search tree structure maps neighborhood patterns to reactions.Range: Uses same two-layer hex range (sqrt(7)d/2 - d) as force calculations.Example: Wood object detects nearby fire → increases heat timer.When: Timer value reaches threshold for transformation.Exclusive Timers: Each object has one active timer (saves memory).Timer Types: Burning, freezing, electrified, etc. (exact types TBD).Timer Modifications: Environmental reactions can increase/decrease/reset timer values or swap timer types.Transformations: When timer reaches threshold, object type transforms based on timer type.
Timer Type: Limited set of timer types (bit count TBD - see cross-referenceShader Data Layout).Timer Value: Count-up timer (bit count TBD).Exclusive: Only one active timer per object to minimize storage.Reset on Transformation: All type transformations reset timer to zero.Increase/Decrease: Environmental reactions modify timer value.Type Swap: Reactions can change which timer type is active.Threshold Check: When timer value exceeds threshold, transformation triggers.Examples: Wood near fire → heat timer increases → at threshold, wood transforms to fire Water near fire → fire timer decreases → at threshold, fire extinguishes Gather Pattern: Each object examines its two-layer hex neighborhood.Search Tree Lookup: Neighbor configuration maps to reaction data via search tree.Reaction Data: Includes timer modifications, type swaps, and transformation rules.Combined Effects: Neighbor combinations may have distinct reactions (not independent).Current State: Object considers its current timer type and value.Neighbor Pattern: Looks up reaction based on nearby object types.Modifications: Swap timer type Set timer value Increase/decrease timer value Immediate type transformation (if applicable) Example: Wood object with heat timer near fire → heat timer increases by X per frame.⚠️ TODO: Design how reactions can create objects on different layers.Constraint: Maintain one-object-per-cell guarantee within each layer.Possibility: Object on one layer creates object on different layer in same or neighboring cell.Use Case: Fire (air layer) creating ash (ground layer), explosions creating debris, etc.Key: Ordered or unordered pair of object types (type_a, type_b).Value: New object type after merging.Properties: New object inherits mass from type, velocity from mass-weighted average.Element Handling: If types have elements, use element combination rules.Apply Forces + Move: Environmental reactions happen during force application.Overlap Passes: Merge reactions happen during object merging.Set Grid Position: Reactions complete before grid position updates.Frequency: Reactions run every physics frame (60fps).
See Pipeline Passes for multi-pass coordination.Shared Neighborhood: Use same two-layer hex data loaded for forces.Combined Shaders: Environmental reactions integrated into force application shader.Memory Efficiency: Reuse neighborhood cache for both forces and reactions.Basic: Object type changes (e.g., wood → fire).Properties Updated: Mass and other properties update based on new type.Timer Reset: Timer returns to zero on transformation.Removal: Object not output to next pass, removed from simulation.Use Case: Fire extinguished by water, objects consumed by reactions.⚠️ TODO: Cross-layer creation design needed.Constraint: Respect one-per-cell within each layer.Examples: Fire creating smoke, explosions creating particles.]]>architecture/systems/physics/reactions.htmlarchitecture/systems/physics/reactions.mdWed, 12 Nov 2025 05:24:27 GMTDeterminism for fixed-point arithmetic implementation.Vector Representation: Two-component velocity (x,y) stored with fixed-point precision.Texture Storage: Velocities stored in GPU textures alongside position data.Deterministic Updates: All velocity changes use fixed-point arithmetic for cross-platform consistency.Frame Persistence: Velocity persists frame-to-frame unless modified by forces.Applied Forces: Collision, cohesion, and spell forces modify velocity each frame.
See Cohesion for gap-closing attraction
See Collision for overlap repulsion
See Spell Integration for spell-driven forces Mass Response: Velocity change determined by F=ma (acceleration inversely proportional to mass).Object Merging: Merged objects receive mass-weighted average velocity.Damping: ⚠️ TBD - Optional velocity damping to prevent perpetual motion (needs playtesting).Maximum Velocity: ~9.69 hex cells/second at 60fps based on two-layer force range guarantee.Gameplay Range: Typical gameplay velocities 2-6 cells/second, providing margin for force application.Range Guarantee: Two hex layers sufficient for all force interactions within speed limits.Type-Based: Each object type has an associated mass value.Layer Variation: Different layers may have different mass ranges (e.g., ground heavier than air).Gameplay Impact: Mass affects force response and merging outcomes.⚠️ NEEDS SPECIFICATION: Specific mass values for object types TBD through gameplay balancing.Force Response: Heavier objects accelerate less from the same applied force (a = F/m).Collision Interaction: Mass ratio between colliding objects affects their relative acceleration responses.Momentum Conservation: When objects merge, velocities are mass-averaged to conserve total momentum:m1*v1 + m2*v2 + ... = m_combined * v_combined
See Object Merging for combination mechanics.Position: Hex cell coordinates (using polar/cube system) Fixed-point offset (x,y) from cell center Velocity: Fixed-point vector (x,y) Stored in GPU texture alongside position Properties: Object type ID (for mass lookup and reactions) Mass value (may be stored or computed from type) Layer assignment (Ground/Object/Air) Texture Layout: Data packed efficiently for GPU texture storage and access patterns.Force Application Pass: Velocity updated by accumulated forces in "Apply Forces + Move" pass.Position Update: Sub-grid offset updated by velocity in same pass.Cell Assignment: Final hex cell determined in "Set Grid Position" pass.
See Pipeline Passes for multi-pass execution coordination.Arithmetic: All position and velocity calculations use 16.16 fixed-point format.Overflow Prevention: Calculations designed to prevent overflow in extreme cases.Determinism: Integer-only operations ensure identical results across platforms.Forces modify velocity each frame:
Cohesion - Gap-closing attraction
Collision - Overlap repulsion
Spell Integration - Spell-driven forces
Object Merging - Mass-weighted velocity averaging when objects combine
Reactions - Type transformations affect mass assignment Sub-grid offsets provide precise visual positioning Velocities available for motion blur and particle effects Ground Layer: Terrain foundation (dirt, stone, water) Object Layer: Interactive entities (rocks, trees, creatures, players) Air Layer: Gases and effects (fire, smoke, magic) Each layer maintains independent position and velocity data but shares the same movement mechanics.]]>architecture/systems/physics/movement.htmlarchitecture/systems/physics/movement.mdWed, 12 Nov 2025 05:24:00 GMTElement Effects for which elements create which force types.Overlapping Spells: Objects can be affected by multiple spell shapes simultaneously.Element Combination: When multiple spells overlap, combine elements using cancellation rules.Cast Time Ordering: Process spells in cast time order for deterministic element combination.Force Combination: After element combination, resulting force applied to object.Primary Duty: Most double-element spells trigger tile type transformations in addition to applying forces.Transformation Trigger: When spell activates on a tile, triggers type transformation rules.Physics Integration: Transformations occur during physics pipeline execution. Spell Triggers: Double-element spell activates on specific tiles Type Lookup: Determine target tile type and spell element combination Rule Application: Apply transformation rules based on spell elements Tile Update: Update tile type in physics layer ⚠️ TODO: Triple-element spells will provide passive modifications to reactions and forces for their duration.Design Intent: Global or area-of-effect modifications to physics behavior while spell is active.Implementation: TBD through spell system design.Spell Buffer Lookup: Objects check spell buffer for overlapping spell shapes during force accumulation.Force Calculation: Calculate spell force based on element type and spell properties.Vector Addition: Add spell forces to collision and cohesion forces for net force.Mass Consideration: ⚠️ TBD - Determine if spell forces ignore mass or use standard F=ma.Force Application Pass: Spell forces calculated in "Apply Forces + Move" GPU pass.Transformation Pass: Tile transformations may occur in separate pass or integrated with forces.Coordination: Ensure spell effects and physics forces execute in deterministic order.
See Pipeline Passes for multi-pass execution coordination.Spell Data (per active spell): Shape geometry (circle, rectangle, polygon, etc.) Position and dimensions Element type(s) after cancellation Cast time (for ordering) Force magnitude and direction Trigger status Spatial Partitioning: ⚠️ Future optimization - Partition spells spatially to limit checks per object.Per-Object Lookup: Each object queries spell buffer for overlapping shapes.Overlap Test: Geometric test determines if object center is within spell shape.Parallel Access: All objects can read spell buffer simultaneously (read-only access).Determinism: All force calculations and transformations use fixed-point arithmetic.Precision: Force vectors use 16.16 fixed-point format matching physics calculations.Cross-Platform: Ensures identical spell effects across all hardware.
See cross-referenceDeterminism for fixed-point implementation details.⚠️ NEEDS SPECIFICATION: Complete mapping of spell elements to force behaviors.Expected Categories: Impulse Elements: Push, pull, explosion effects (add to velocity) Velocity-Set Elements: Wind, flow, directional movement (set velocity) Transformation Elements: Tile type changes (double-element duty) Modifier Elements: Physics behavior modifications (triple-element effects) Design Source: Element effects defined in spell system documentation.
See cross-referenceElement Effects for complete element catalog.Shape Evaluation: Spells define shapes that physics checks for overlap.Element System: Element types determine force application method.Trigger Lifecycle: Spell timing determines when forces are applied.Cross-references:
cross-referenceSpell System - Overall spell mechanics
cross-referenceElement Effects - What each element does Forces: Spell forces accumulate with collision and cohesion forces.Movement: Spell forces modify object velocities like any other force.Reactions: Spell transformations may interact with reaction system.Internal references:
Pipeline Passes - GPU execution integration
Cohesion and Collision - Other force sources
Movement - Velocity and position updates
Reactions - Environmental transformations Buffer Size: Number of active spells affects lookup performance.Overlap Tests: Geometric tests must be efficient (many objects checking many spells).Spatial Optimization: Future partitioning can reduce checks per object.GPU Parallelism: Spell force calculations fully parallelizable across objects.Force Balance: Spell forces should be noticeable over ambient physics forces.Element Diversity: Different elements should feel distinct through force behaviors.Gameplay Clarity: Players should understand how spell elements affect physics.Tuning Flexibility: Force magnitudes and behaviors exposed as configuration values.]]>architecture/systems/physics/spell-integration.htmlarchitecture/systems/physics/spell-integration.mdWed, 12 Nov 2025 05:23:22 GMTCohesion, Collision, Spell Forces
Movement: Movement System for velocity and offset detailsObject Merging: Detect objects closer than combination distance d and merge them.Multi-Object Groups: Handle groups of 3+ objects that should all merge together.Cascading Merges: Resolve combinations that create new combinations.Multiple Passes: May require 2-N passes to fully resolve all combinations.Convergence Detection: Terminate when no combinations triggered in previous pass.Pass Skipping: Early exit if no merging activity detected. Detect objects with distance < d Identify merge groups using scatter-gather algorithm Calculate mass-weighted centroid and velocity Apply reaction rules for type transformation Create merged object, remove component objects Check for convergence (no more merges needed)
Merging: Object Merging for combination mechanics
Transformations: Reactions for type changes during mergesHex Cell Assignment: Update which hex cell each object occupies based on final offset.Boundary Wrapping: Handle world edge wrapping for continuous world.Final Position: Establish object positions for next frame and rendering. Read final sub-grid offset from previous pass Determine if offset exceeds hex cell boundary Calculate new hex cell coordinates if needed Adjust offset relative to new cell center Write final position to output texture Dual Textures: Each layer has two textures (read and write).Simultaneous Access: All objects read from one texture, write to the other.Determinism: Prevents read-after-write hazards and ensures consistent ordering.Swap: Textures swap roles between passes (output becomes input for next pass).
See cross-referenceDeterminism for deterministic execution approach.Frame Budget: 16.67ms total frame time.Physics Allocation: Physics should complete in <12ms to leave time for rendering.Pass Budget: Each pass optimized to execute efficiently within time constraints.⚠️ NEEDS DISCUSSION: Timing coordination between physics, reactions, and rendering systems.Sequential Execution: Passes execute in strict order (no overlap between passes).Synchronization: GPU barriers ensure pass completion before next begins.Shared Memory Caching: Load hex neighborhoods once per workgroup to minimize texture reads.Workgroup Size: 8×8 threads (64 total) balances occupancy and shared memory usage.⚠️ NEEDS TUNING: Optimal workgroup size TBD through GPU profiling.Stationary Objects: Skip force calculations for objects with zero velocity and no nearby activity.Convergence: Terminate overlap passes when no more merges detected.Empty Cells: Skip processing for hex cells with no objects.Coalesced Access: Structure memory access patterns for optimal GPU cache utilization.Texture Formats: Use efficient r32uint formats for object data storage.Bit-Packing: Compress object properties to minimize memory bandwidth.Implementation Details: See GPU system documentation for: Buffer layouts and texture formats Workgroup configuration Memory access patterns Shader structure templates Note: Physics documents describe the logic and algorithms; GPU documents describe the technical implementation.
Movement - Velocity, mass, and positioning mechanics
Cohesion - Gap-closing attraction forces
Collision - Overlap repulsion forces
Spell Integration - Spell-driven forces and transformations
Object Merging - Combination mechanics and multi-pass resolution
Reactions - Type transformations during merges and environmental interactions]]>architecture/systems/physics/passes.htmlarchitecture/systems/physics/passes.mdWed, 12 Nov 2025 05:22:42 GMTReactions for type transformation rules.Multiple Passes: May require 2-N overlap passes to fully resolve cascading combinations.Convergence Detection: Terminate when no more objects need merging.Pass Skipping: Early termination if no combinations triggered in previous pass.
See Pipeline Passes for multi-pass coordination.Determinism: All position and velocity calculations use fixed-point arithmetic.Precision: Mass-weighted averaging maintains fixed-point format throughout.Overflow Prevention: Weighted calculations designed to prevent overflow in extreme cases.
See cross-referenceDeterminism for fixed-point implementation details.Challenge: Identifying all objects in merge group requires coordination across GPU threads.Atomic Operations: May use atomic operations to flag objects for combination.Multiple Passes: Iterative approach resolves combinations step by step.Input: Object positions and velocities from previous pass.Processing: Detect nearby objects, calculate merged properties, apply transformations.Output: Updated object layout with merged objects replacing separate objects.Transition Point: At distance > d, collision forces apply; at distance < d, merging takes over.Smooth Handoff: No force application during merge (combination replaces force-based separation).
See Collision for repulsion force mechanics.Type Transformation: Merging triggers reaction rules to determine new object type.Environmental Context: Reactions may consider environmental factors in transformation.
See Reactions for transformation rules and environmental interactions.Convergence Speed: Most combinations should resolve in 2-3 passes.Early Termination: Stop iteration when no combinations detected.Workgroup Coordination: Efficient GPU implementation critical for performance with many objects.Threshold Tuning: Distance d must balance gameplay feel with physics stability.Mass Conservation: Consider whether mass should be conserved or type-determined in merges.Gameplay Impact: Merging creates strategic depth through spatial positioning and object manipulation.]]>architecture/systems/physics/object-merging.htmlarchitecture/systems/physics/object-merging.mdWed, 12 Nov 2025 05:22:05 GMTMovement System for mass properties and velocity updates.Distance Threshold: When objects closer than combination distance d, merging takes over.Force Cutoff: Collision forces stop applying at very close range (handled by combination instead).Transition: Smooth transition from force-based separation to combination-based merging.
See Object Merging for combination mechanics.Opposing Forces: Collision (repulsion) must overcome cohesion (attraction) for objects to separate.Stable Equilibrium: Forces should balance to maintain object spacing without oscillation.Dominance: Collision forces typically stronger at close range than cohesion at same distance.
See Cohesion for attraction force mechanics.Determinism: All calculations use fixed-point arithmetic for cross-platform consistency.Precision: Distance and force calculations use 16.16 fixed-point format.Overflow Prevention: Force magnitude clamped to prevent fixed-point overflow in extreme cases.
See cross-referenceDeterminism for fixed-point implementation details.Pass Integration: Collision forces calculated in "Apply Forces + Move" GPU pass.Neighborhood Caching: Two-layer hex neighborhood loaded into workgroup shared memory.Parallel Processing: Each object independently calculates collision forces from neighbors.
See Pipeline Passes for integration with multi-pass GPU execution.Neighbor Limits: Two-layer range constraint keeps collision calculations bounded.Early Termination: Skip collision calculations for stationary objects with no nearby motion.Shared Memory: Workgroup caching minimizes texture reads for neighbor data.Playtesting Required: Collision formula will be refined through gameplay iteration.Adjustable Parameters: Force strength and response curve exposed as configuration values.Gameplay Feel: Balance between realistic physics response and responsive, fun gameplay.]]>architecture/systems/physics/collision.htmlarchitecture/systems/physics/collision.mdWed, 12 Nov 2025 05:21:29 GMTDeterminism for fixed-point implementation details.Pass Integration: Cohesion forces calculated in "Apply Forces + Move" GPU pass.Neighborhood Caching: Two-layer hex neighborhood loaded into workgroup shared memory.Parallel Processing: Each object independently calculates cohesion forces from neighbors.
See Pipeline Passes for integration with multi-pass GPU execution.Neighbor Limits: Two-layer range constraint keeps cohesion calculations bounded and efficient.Early Termination: Skip cohesion calculations for stationary objects with no nearby activity.Shared Memory: Workgroup caching minimizes texture reads for neighbor data.Playtesting Required: Cohesion formula and radius will be refined through gameplay iteration.Adjustable Parameters: Force strength and radius exposed as configuration values for tuning.Gameplay Feel: Balance between maintaining density and allowing dynamic, responsive movement.]]>architecture/systems/physics/cohesion.htmlarchitecture/systems/physics/cohesion.mdWed, 12 Nov 2025 05:21:08 GMTPhysics System for implementation details Multiplayer relies on determinism for: State synchronization between clients and server Client-side prediction and rollback Replay validation and cheat detection
See cross-referenceMultiplayer System for integration details All Changes: Consider determinism impact before implementing any physics/gameplay changes.Code Review: Explicit review of determinism implications required.Testing: Validate determinism before and after modifications.Floating-Point Math: Never use floating-point in gameplay logic.Random Numbers: Use deterministic RNG with consistent seeding.Timing Dependencies: Don't rely on wall-clock time or variable frame timing.Undefined Ordering: Ensure all operations have well-defined execution order.]]>architecture/general/determinism.htmlarchitecture/general/determinism.mdWed, 12 Nov 2025 05:20:28 GMTarchitecture/general/implementation-guide.htmlarchitecture/general/implementation-guide.mdWed, 12 Nov 2025 03:44:51 GMTarchitecture/systems/multiplayer/multiplayer.htmlarchitecture/systems/multiplayer/multiplayer.mdWed, 12 Nov 2025 03:40:48 GMTarchitecture/general/state-management.htmlarchitecture/general/state-management.mdWed, 12 Nov 2025 03:37:27 GMTarchitecture/general/data-flow.htmlarchitecture/general/data-flow.mdWed, 12 Nov 2025 03:37:22 GMTarchitecture/systems/multiplayer/performance.htmlarchitecture/systems/multiplayer/performance.mdWed, 12 Nov 2025 03:36:52 GMTarchitecture/systems/multiplayer/security.htmlarchitecture/systems/multiplayer/security.mdWed, 12 Nov 2025 03:36:48 GMTarchitecture/systems/multiplayer/network-protocol.htmlarchitecture/systems/multiplayer/network-protocol.mdWed, 12 Nov 2025 03:36:42 GMTarchitecture/systems/multiplayer/server-architecture.htmlarchitecture/systems/multiplayer/server-architecture.mdWed, 12 Nov 2025 03:36:37 GMTarchitecture/systems/multiplayer/deployment.htmlarchitecture/systems/multiplayer/deployment.mdWed, 12 Nov 2025 03:36:31 GMTdevelopment/getting-started.htmldevelopment/getting-started.mdWed, 12 Nov 2025 03:13:46 GMTcohesion: [implementation] Determine cohesion force formula through playtesting[implementation] Determine cohesion radius through playtesting[testing] Validate cohesion interaction with collision forces
collision: [implementation] Determine collision force formula through playtesting[testing] Validate collision response with various mass ratios[discussion] Balance between collision force and combination trigger threshold
config: Define configuration system architectureDocument configuration file formatsAdd runtime configuration managementDocument environment-specific settings
core-mechanics: [discussion] Confirm healing mechanics approach (no healing vs tile-based healing zones)[discussion] Map size constraints for optimal performance
customization: [discussion] Curse system implementation details[discussion] Curse stacking rules and limits
deck-building: [discussion] Maximum deck size limits[discussion] Spell acquisition and progression system
determinism: [implementation] Specify exact fixed-point formats for velocity and position[implementation] Implement cross-platform validation test suite[testing] Validate determinism across different GPU architectures
docs: Complete main documentation indexAdd project overview sectionAdd getting started quick links
element-effects: [design] Define force types and magnitudes for all 26 elements[design] Define tile transformation effects for double-element spells[design] Define passive modifications for triple-element spells[discussion] Determine which elements use impulse vs velocity-set forces
element-system: [discussion] Void rune effects[discussion] Triple element spell niche uses
general: [documentation] Update navigation to mark outdated documents[documentation] Remove active region references
mana-system: [discussion] Flower recharge timing balance - 3-turn cycle interaction with action cooldown
movement: [discussion] Define mass values for different object types across all layers[testing] Validate velocity damping needs through playtesting
object-merging: [implementation] Specify exact combination distance threshold d[implementation] Implement scatter-gather algorithm for multi-object merges[testing] Validate momentum conservation in merges
overview: [discussion] Mass values for different tile types in collision physics[documentation] Document actual determinism approach (simultaneous read/write passes)
passes: [implementation] Determine optimal number of overlap passes through profiling[discussion] Frame timing coordination with reactions and rendering
performance: [documentation] Rewrite performance strategy without active regions[discussion] Alternative optimization approaches without active regions
reactions: [design] Change object merging so second overlap prevents creation (no triple+ merges)[design] Design cross-layer object creation during reactions[design] Triple-element spells will provide passive modifications to reactions and forces for their duration[implementation] Build hashmap structure for merge reactions (type pairs -> new type)[implementation] Design search tree for environmental reaction lookups[discussion] Define all timer types needed (burning, freezing, electrified, etc.)[discussion] Define all reaction rules (merges and environmental)
shader-data-layout: [implementation] List all data fields needed in GPU shader passes[implementation] Determine bit allocation for each field[implementation] Calculate total storage requirements per object[implementation] Optimize bit-packing to minimize texture memory usage[discussion] Determine timer type bit count based on number of timer types needed[discussion] Determine timer value bit count based on maximum time duration needed
spell-integration: [discussion] Define which spell elements use impulses vs velocity setting[implementation] Specify spell force magnitudes per element[discussion] Determine if spell forces ignore mass or not[design] Triple-element spells will provide passive modifications to reactions and forces for their duration
spells-and-runes: [discussion] Number of casting slots/pools - using 4 as example, final count TBD[discussion] Obstruction checks for line of sight[discussion] Specific shape primitives for spell design[discussion] Single element rune additional effects beyond mana recharge
technical-decisions: [discussion] Specific mass values for different tile types in collision physics[discussion] Frame rate coordination between physics, reactions, and rendering
ui: Define UI system architectureDocument component hierarchyAdd interaction patternsDocument accessibility requirements All Warnings
cpu-architecture: [outdated] Entire file - Spell system now fully GPU-accelerated, not CPU-based
determinism: [proposed] Fixed-point precision needs validation through testing
element-effects: [proposed] Element effects are design proposals awaiting gameplay testing
general: [outdated] Active Region System referenced but not being implemented[outdated] Multiple linked documents describe outdated approaches (implementation-guide, data-flow)
mana-system: [outdated] All fire/water/earth/air references removed - replaced with 6-element system
object-merging: [proposed] Scatter-gather implementation approach needs specification
overview: [outdated] Active region optimization references removed - system not being implemented[outdated] data-flow.md reference is outdated
performance: [outdated] Active Region System section describes system that is NOT being implemented[outdated] 32×32 chunk references throughout document
spell-integration: [proposed] Element-to-force mapping needs spell system design completion
spells: [outdated] Previously mentioned CPU-only design - now fully GPU-accelerated
spells-and-runes: [outdated] Previously mentioned CPU processing - now fully GPU-accelerated Files by Status Implementation Tasks
shader-data-layout: [implementation] List all data fields needed in GPU shader passes[implementation] Determine bit allocation for each field[implementation] Calculate total storage requirements per object[implementation] Optimize bit-packing to minimize texture memory usage[discussion] Determine timer type bit count based on number of timer types needed[discussion] Determine timer value bit count based on maximum time duration needed
shader-data-layout: [implementation] List all data fields needed in GPU shader passes[implementation] Determine bit allocation for each field[implementation] Calculate total storage requirements per object[implementation] Optimize bit-packing to minimize texture memory usage[discussion] Determine timer type bit count based on number of timer types needed[discussion] Determine timer value bit count based on maximum time duration needed
shader-data-layout: [implementation] List all data fields needed in GPU shader passes[implementation] Determine bit allocation for each field[implementation] Calculate total storage requirements per object[implementation] Optimize bit-packing to minimize texture memory usage[discussion] Determine timer type bit count based on number of timer types needed[discussion] Determine timer value bit count based on maximum time duration needed
shader-data-layout: [implementation] List all data fields needed in GPU shader passes[implementation] Determine bit allocation for each field[implementation] Calculate total storage requirements per object[implementation] Optimize bit-packing to minimize texture memory usage[discussion] Determine timer type bit count based on number of timer types needed[discussion] Determine timer value bit count based on maximum time duration needed
determinism: [implementation] Specify exact fixed-point formats for velocity and position[implementation] Implement cross-platform validation test suite[testing] Validate determinism across different GPU architectures
determinism: [implementation] Specify exact fixed-point formats for velocity and position[implementation] Implement cross-platform validation test suite[testing] Validate determinism across different GPU architectures
reactions: [design] Change object merging so second overlap prevents creation (no triple+ merges)[design] Design cross-layer object creation during reactions[design] Triple-element spells will provide passive modifications to reactions and forces for their duration[implementation] Build hashmap structure for merge reactions (type pairs -> new type)[implementation] Design search tree for environmental reaction lookups[discussion] Define all timer types needed (burning, freezing, electrified, etc.)[discussion] Define all reaction rules (merges and environmental)
reactions: [design] Change object merging so second overlap prevents creation (no triple+ merges)[design] Design cross-layer object creation during reactions[design] Triple-element spells will provide passive modifications to reactions and forces for their duration[implementation] Build hashmap structure for merge reactions (type pairs -> new type)[implementation] Design search tree for environmental reaction lookups[discussion] Define all timer types needed (burning, freezing, electrified, etc.)[discussion] Define all reaction rules (merges and environmental)
cohesion: [implementation] Determine cohesion force formula through playtesting[implementation] Determine cohesion radius through playtesting[testing] Validate cohesion interaction with collision forces
cohesion: [implementation] Determine cohesion force formula through playtesting[implementation] Determine cohesion radius through playtesting[testing] Validate cohesion interaction with collision forces
collision: [implementation] Determine collision force formula through playtesting[testing] Validate collision response with various mass ratios[discussion] Balance between collision force and combination trigger threshold
object-merging: [implementation] Specify exact combination distance threshold d[implementation] Implement scatter-gather algorithm for multi-object merges[testing] Validate momentum conservation in merges
object-merging: [implementation] Specify exact combination distance threshold d[implementation] Implement scatter-gather algorithm for multi-object merges[testing] Validate momentum conservation in merges
passes: [implementation] Determine optimal number of overlap passes through profiling[discussion] Frame timing coordination with reactions and rendering
spell-integration: [discussion] Define which spell elements use impulses vs velocity setting[implementation] Specify spell force magnitudes per element[discussion] Determine if spell forces ignore mass or not[design] Triple-element spells will provide passive modifications to reactions and forces for their duration Testing Tasks
determinism: [implementation] Specify exact fixed-point formats for velocity and position[implementation] Implement cross-platform validation test suite[testing] Validate determinism across different GPU architectures
cohesion: [implementation] Determine cohesion force formula through playtesting[implementation] Determine cohesion radius through playtesting[testing] Validate cohesion interaction with collision forces
collision: [implementation] Determine collision force formula through playtesting[testing] Validate collision response with various mass ratios[discussion] Balance between collision force and combination trigger threshold
object-merging: [implementation] Specify exact combination distance threshold d[implementation] Implement scatter-gather algorithm for multi-object merges[testing] Validate momentum conservation in merges
movement: [discussion] Define mass values for different object types across all layers[testing] Validate velocity damping needs through playtesting Discussion Items
overview: [discussion] Mass values for different tile types in collision physics[documentation] Document actual determinism approach (simultaneous read/write passes)
performance: [documentation] Rewrite performance strategy without active regions[discussion] Alternative optimization approaches without active regions
shader-data-layout: [implementation] List all data fields needed in GPU shader passes[implementation] Determine bit allocation for each field[implementation] Calculate total storage requirements per object[implementation] Optimize bit-packing to minimize texture memory usage[discussion] Determine timer type bit count based on number of timer types needed[discussion] Determine timer value bit count based on maximum time duration needed
shader-data-layout: [implementation] List all data fields needed in GPU shader passes[implementation] Determine bit allocation for each field[implementation] Calculate total storage requirements per object[implementation] Optimize bit-packing to minimize texture memory usage[discussion] Determine timer type bit count based on number of timer types needed[discussion] Determine timer value bit count based on maximum time duration needed
technical-decisions: [discussion] Specific mass values for different tile types in collision physics[discussion] Frame rate coordination between physics, reactions, and rendering
technical-decisions: [discussion] Specific mass values for different tile types in collision physics[discussion] Frame rate coordination between physics, reactions, and rendering
reactions: [design] Change object merging so second overlap prevents creation (no triple+ merges)[design] Design cross-layer object creation during reactions[design] Triple-element spells will provide passive modifications to reactions and forces for their duration[implementation] Build hashmap structure for merge reactions (type pairs -> new type)[implementation] Design search tree for environmental reaction lookups[discussion] Define all timer types needed (burning, freezing, electrified, etc.)[discussion] Define all reaction rules (merges and environmental)
reactions: [design] Change object merging so second overlap prevents creation (no triple+ merges)[design] Design cross-layer object creation during reactions[design] Triple-element spells will provide passive modifications to reactions and forces for their duration[implementation] Build hashmap structure for merge reactions (type pairs -> new type)[implementation] Design search tree for environmental reaction lookups[discussion] Define all timer types needed (burning, freezing, electrified, etc.)[discussion] Define all reaction rules (merges and environmental)
collision: [implementation] Determine collision force formula through playtesting[testing] Validate collision response with various mass ratios[discussion] Balance between collision force and combination trigger threshold
passes: [implementation] Determine optimal number of overlap passes through profiling[discussion] Frame timing coordination with reactions and rendering
spell-integration: [discussion] Define which spell elements use impulses vs velocity setting[implementation] Specify spell force magnitudes per element[discussion] Determine if spell forces ignore mass or not[design] Triple-element spells will provide passive modifications to reactions and forces for their duration
spell-integration: [discussion] Define which spell elements use impulses vs velocity setting[implementation] Specify spell force magnitudes per element[discussion] Determine if spell forces ignore mass or not[design] Triple-element spells will provide passive modifications to reactions and forces for their duration
movement: [discussion] Define mass values for different object types across all layers[testing] Validate velocity damping needs through playtesting
customization: [discussion] Curse system implementation details[discussion] Curse stacking rules and limits
customization: [discussion] Curse system implementation details[discussion] Curse stacking rules and limits
deck-building: [discussion] Maximum deck size limits[discussion] Spell acquisition and progression system
deck-building: [discussion] Maximum deck size limits[discussion] Spell acquisition and progression system
element-system: [discussion] Void rune effects[discussion] Triple element spell niche uses
element-system: [discussion] Void rune effects[discussion] Triple element spell niche uses
mana-system: [discussion] Flower recharge timing balance - 3-turn cycle interaction with action cooldown
spells-and-runes: [discussion] Number of casting slots/pools - using 4 as example, final count TBD[discussion] Obstruction checks for line of sight[discussion] Specific shape primitives for spell design[discussion] Single element rune additional effects beyond mana recharge
spells-and-runes: [discussion] Number of casting slots/pools - using 4 as example, final count TBD[discussion] Obstruction checks for line of sight[discussion] Specific shape primitives for spell design[discussion] Single element rune additional effects beyond mana recharge
spells-and-runes: [discussion] Number of casting slots/pools - using 4 as example, final count TBD[discussion] Obstruction checks for line of sight[discussion] Specific shape primitives for spell design[discussion] Single element rune additional effects beyond mana recharge
spells-and-runes: [discussion] Number of casting slots/pools - using 4 as example, final count TBD[discussion] Obstruction checks for line of sight[discussion] Specific shape primitives for spell design[discussion] Single element rune additional effects beyond mana recharge
element-effects: [design] Define force types and magnitudes for all 26 elements[design] Define tile transformation effects for double-element spells[design] Define passive modifications for triple-element spells[discussion] Determine which elements use impulse vs velocity-set forces
core-mechanics: [discussion] Confirm healing mechanics approach (no healing vs tile-based healing zones)[discussion] Map size constraints for optimal performance
core-mechanics: [discussion] Confirm healing mechanics approach (no healing vs tile-based healing zones)[discussion] Map size constraints for optimal performance Research Items Dataview: No results to show for list query. Documentation Tasks
general: [documentation] Update navigation to mark outdated documents[documentation] Remove active region references
general: [documentation] Update navigation to mark outdated documents[documentation] Remove active region references
overview: [discussion] Mass values for different tile types in collision physics[documentation] Document actual determinism approach (simultaneous read/write passes)
performance: [documentation] Rewrite performance strategy without active regions[discussion] Alternative optimization approaches without active regions Review Tasks Dataview: No results to show for list query. Proposed Systems
determinism: [proposed] Fixed-point precision needs validation through testing
object-merging: [proposed] Scatter-gather implementation approach needs specification
spell-integration: [proposed] Element-to-force mapping needs spell system design completion
element-effects: [proposed] Element effects are design proposals awaiting gameplay testing Outdated Documents
general: [outdated] Active Region System referenced but not being implemented[outdated] Multiple linked documents describe outdated approaches (implementation-guide, data-flow)
general: [outdated] Active Region System referenced but not being implemented[outdated] Multiple linked documents describe outdated approaches (implementation-guide, data-flow)
overview: [outdated] Active region optimization references removed - system not being implemented[outdated] data-flow.md reference is outdated
overview: [outdated] Active region optimization references removed - system not being implemented[outdated] data-flow.md reference is outdated
performance: [outdated] Active Region System section describes system that is NOT being implemented[outdated] 32×32 chunk references throughout document
performance: [outdated] Active Region System section describes system that is NOT being implemented[outdated] 32×32 chunk references throughout document
cpu-architecture: [outdated] Entire file - Spell system now fully GPU-accelerated, not CPU-based
mana-system: [outdated] All fire/water/earth/air references removed - replaced with 6-element system
spells-and-runes: [outdated] Previously mentioned CPU processing - now fully GPU-accelerated
spells: [outdated] Previously mentioned CPU-only design - now fully GPU-accelerated Breaking Changes Dataview: No results to show for list query. Performance Concerns Dataview: No results to show for list query. Security Concerns Dataview: No results to show for list query. Technical Debt Dataview: No results to show for list query. Stub Files Proposed Documents Outdated Documents Dataview: No results to show for table query.
Note: This page automatically aggregates todos, warnings, and status information from frontmatter metadata across all documentation files. For complete documentation on how to use frontmatter fields (status, tags, todo categories, warning types) and integration with the documentation structure, see cross-referenceFrontmatter Metadata Documentation.]]>development/tasklist.htmldevelopment/tasklist.mdWed, 12 Nov 2025 02:57:10 GMTGetting Started - Project setup and first build
Development Principles - Core values and guidelines for contributors
Documentation Structure - How to organize and navigate documentation
Building Documentation - Export and deploy documentation to GitHub Pages
Task List - Auto-generated TODO items, warnings, and documentation status npm install npm run dev # Development server npm run test # Test suite npm run build # Production build npm run lint # ESLint npm run format # Prettier Core types: src/core/types.ts Spell types: src/spell-system/types.ts Documentation: docs/ Architecture: docs/architecture/
See Development Principles for core values and Documentation Structure for information organization guidelines.]]>development/development.htmldevelopment/development.mdWed, 12 Nov 2025 02:56:53 GMTArchitecture - System design and technical approach
cross-referenceDevelopment - Setup, workflow, and development processes
cross-referenceGameplay - Core game mechanics and design philosophy
cross-referenceLegacy V1 Analysis - V1 system concepts for V2 development reference
Development Setup: See cross-referenceGetting Started Guide
Architecture Overview: Read cross-referenceSystem Overview
Development Principles: Review cross-referenceCore Principles npm run dev # Start development server npm run test # Run test suite npm run build # Create production build /docs - Documentation source (Markdown) /src - Source code /tests - Test suites /build - Build outputs (gitignored)
GitHub Repository
cross-referenceBuilding Documentation
Full Documentation Index For detailed documentation, explore the links above or browse the documentation tree.]]>index.htmlindex.mdWed, 12 Nov 2025 02:56:29 GMTdevelopment/development-principles.htmldevelopment/development-principles.mdTue, 11 Nov 2025 23:46:20 GMTSpell System for complete spell mechanics.Element Mastery: Understanding 26 elements and geometric opposition structure Recognizing cancellation opportunities (complete, partial, Void) Defensive counter-element selection against opponents Resource Management: Mana flower spending patterns with timed recharge cycles Action cooldown timing (cast/load/refresh decisions) Refresh action strategic use (tempo cost for pool cycling) Deck Construction: Pre-match element focus vs diverse coverage decisions Mana flower conversion optimization (2:1 trade-off) Singleton format encourages spell variety strategies Tactical Execution: Slot/pool management (when to cast vs load) Directional targeting precision Spell overlap timing for combinations Rule Interactions: Complex behaviors arising from rule combinations Adaptive Strategy: Changing world state requires flexible tactical adaptation Risk/Reward: Curse system and aggressive positioning create choices Long-term Planning: Pre-planning system rewards strategic foresight Element Counter-Play: Geometric opposition creates natural counter-strategies ]]>gameplay/core-mechanics.htmlgameplay/core-mechanics.mdTue, 11 Nov 2025 22:32:58 GMTSystem Overview - Complete architectural design and module relationships
General Architecture - Core architectural concepts and design patterns
Systems - Individual system modules and implementations ]]>architecture/architecture.htmlarchitecture/architecture.mdTue, 11 Nov 2025 22:12:22 GMTArchitecture - System design and technical approach
Development - Setup, workflow, and development processes
Gameplay - Core game mechanics and design philosophy TODO: Add quick start section with: Project setup instructions First build steps Development environment configuration TODO: Add project overview with: Game concept summary Technical architecture highlights Development status and roadmap 🚧 This file is a stub and needs completion]]>docs.htmldocs.mdTue, 11 Nov 2025 21:24:24 GMTTask List for automated queries that collect and organize these items across all documentation. Use status to track document maturity through its lifecycle Apply tags for broad categorization (multiple tags allowed) Subcategorize todo items to help with task filtering and prioritization Subcategorize warnings to identify types of concerns at a glance Update status as documents progress from draft → proposed → approved → implemented Mark documents as outdated when code diverges from documentation The goal is that readers can efficiently find exactly what they need without encountering duplicate or outdated information.]]>development/documentation-structure.htmldevelopment/documentation-structure.mdMon, 13 Oct 2025 19:47:30 GMTSpell System - Player spellcasting and mana management
Physics Engine - GPU-accelerated movement, collisions, and reactions
Renderer - Visual display and UI rendering
Multiplayer - Real-time PvP networking
User Interface - Game controls, HUD elements, and player interaction
Configuration - System settings and runtime parameters
GPU Manager - WebGPU resource management and coordination ]]>architecture/systems/systems.htmlarchitecture/systems/systems.mdSat, 08 Nov 2025 05:21:41 GMTarchitecture/systems/physics/determinism.htmlarchitecture/systems/physics/determinism.mdFri, 07 Nov 2025 00:58:21 GMTForces for force formulas and mechanics.Purpose: Detect objects closer than combination distance d; merge them into single objects.Scatter-Gather: Complex algorithm to identify and merge groups of nearby objects.Multiple Passes: May require several passes to fully resolve cascading combinations.⚠️ NEEDS SPECIFICATION: Exact scatter-gather implementation approach TBD.@compute @workgroup_size(8, 8) fn overlap_detection_pass( @builtin(global_invocation_id) global_id: vec3<u32>, @builtin(local_invocation_id) local_id: vec3<u32> ) { let hex_coord = calculate_hex_coord(global_id); let object = read_object(hex_coord); if (!object.exists) { return; } // Load two-layer hex neighborhood load_hex_neighborhood_to_cache(hex_coord, local_id); workgroupBarrier(); // Find all objects within combination distance d var nearby_objects = find_objects_within_distance(object, neighborhood_cache, COMBINATION_DISTANCE); if (nearby_objects.count > 0) { // Mark for combination // TODO: Implement scatter-gather algorithm // - Assign combination group ID // - Calculate combined properties (mass-averaged velocity, centroid position) // - Apply reaction rules for type transformation // - Write combined object, mark merged objects for deletion } } Distance Check: Calculate distance between object centers; trigger if < d.Group Formation: All objects within d of combined center merge together.Property Calculation: Velocity: Mass-weighted average of all merged objects Position: Mass-weighted centroid
Type: Determined by reaction rules (see cross-referenceReaction System) Mass: Based on new type Atomic Operations: Use atomics to prevent race conditions when multiple groups overlap.Purpose: Update which hex cell each object occupies based on its final sub-grid offset.Boundary Wrapping: Handle objects that have moved across world edges.Spatial Indexing: Ensure objects are correctly indexed for next frame's neighbor queries.@compute @workgroup_size(8, 8) fn set_grid_position( @builtin(global_invocation_id) global_id: vec3<u32> ) { let hex_coord = calculate_hex_coord(global_id); let object = read_object(hex_coord); if (!object.exists) { return; } // Calculate new hex cell based on offset let new_hex_coord = calculate_hex_from_offset(hex_coord, object.offset); // Normalize offset relative to new cell center let normalized_offset = normalize_offset_to_cell(object.offset, new_hex_coord); // Handle world wrapping let wrapped_coord = wrap_hex_coordinate(new_hex_coord); if (wrapped_coord != hex_coord) { // Object moved to new cell - relocate it object.offset = normalized_offset; atomic_write_object(wrapped_coord, object); delete_object(hex_coord); } else { // Object stayed in same cell - just update offset object.offset = normalized_offset; write_object(hex_coord, object); } } Coordinate System: Use cube coordinates (q, r, s) where q + r + s = 0.Neighbor Lookup: Efficient neighbor calculation using coordinate offsets.Point-to-Hex: Convert Cartesian (x, y) position to hex coordinates using cube algorithm.GPU Layout: Grid stored as skewed parallelogram in texture memory.Rectangular Indexing: Standard 2D texture coordinates map to hex cells.Wrapped Boundaries: World edges wrap seamlessly for continuous circular world.Layer Definition: Objects check 19 hex cells (center + 6 immediate + 12 second-layer).Shared Memory Size: 19 objects fit efficiently in workgroup shared memory.Coordinate Calculation: Precompute neighbor offsets for each hex layer.Purpose: Load neighborhood data once per workgroup to minimize texture reads.Cache Size: 19 hex cells × object data size (position, velocity, type, mass).Synchronization: Workgroup barriers ensure all threads see cached data.// Workgroup shared memory for hex neighborhood var<workgroup> neighborhood_cache: array<ObjectData, 19>; var<workgroup> cache_loaded: bool; fn load_hex_neighborhood_to_cache( center_hex: vec2<i32>, local_id: vec3<u32> ) { // First thread loads all 19 neighbors if (local_id.x == 0 && local_id.y == 0) { for (var i = 0; i < 19; i++) { let neighbor_hex = center_hex + HEX_NEIGHBOR_OFFSETS[i]; neighborhood_cache[i] = read_object(neighbor_hex); } cache_loaded = true; } } Current Choice: 8×8 workgroups (64 threads).Rationale: Balance between GPU occupancy and shared memory usage.⚠️ NEEDS TUNING: Optimal workgroup size TBD through GPU profiling.GPU Texture Layout:struct ObjectData { // Position (12 bytes) hex_coord: vec2<i32>, // 8 bytes - hex cell coordinates offset: vec2<i32>, // 8 bytes - fixed-point offset from cell center // Velocity (8 bytes) velocity: vec2<i32>, // 8 bytes - fixed-point velocity vector // Properties (8 bytes) type_id: u32, // 4 bytes - object type mass: u32, // 4 bytes - mass (or could be computed from type) // Flags (4 bytes) layer: u32, // 4 bytes - Ground/Object/Air (could be packed) exists: bool, // 1 byte - object exists flag // ... potential padding or additional flags } // Total: ~32 bytes per object (may be optimized with bit-packing) Memory Packing: Consider bit-packing to reduce texture memory and bandwidth.Structure: Array of active spell shapes in GPU buffer.Data Per Spell: Shape geometry (circle, rectangle, etc.) Position and radius Element type(s) Cast time (for element combination ordering) Force magnitude/velocity value Spatial Partitioning: Future optimization to limit spell checks per object.Integer-Only Operations: All physics calculations use fixed-point (scaled integers).Platform Independence: Avoids floating-point precision differences across GPUs.Bit Precision: Balance accuracy vs overflow risk (e.g., 16.16 fixed-point).
Details: See cross-referenceDeterminism for implementation.// Fixed-point addition (trivial) fn fixed_point_add(a: vec2<i32>, b: vec2<i32>) -> vec2<i32> { return a + b; } // Fixed-point multiplication (scale factor = 2^16) fn fixed_point_multiply(a: i32, b: i32) -> i32 { return (i64(a) * i64(b)) >> 16; } // Fixed-point division fn fixed_point_divide(numerator: i32, denominator: i32) -> i32 { return (i64(numerator) << 16) / i64(denominator); } Stationary Objects: Skip force calculations for objects with zero velocity and no nearby activity.Convergence Detection: In overlap passes, terminate early if no combinations triggered.Pass Skipping: Skip remaining overlap passes once no objects need merging.Coalesced Access: Threads in workgroup access contiguous memory locations.Texture Cache: Structure data layout for optimal GPU cache utilization.Bit-Packing: Compress object data to minimize texture memory bandwidth.Combination Conflicts: Use atomic operations when multiple objects try to merge.Cell Relocation: Atomic writes when moving objects to new hex cells.Flag Updates: Atomic flags for convergence detection across workgroups. Pipeline implements movement, velocity, and combination mechanics
See cross-referenceMovement System for conceptual details Force calculation details and formulas
See cross-referenceForces for force types and equations Spell buffer provides force input Objects check for overlapping spell shapes
See cross-referenceSpell System for spell mechanics Combination type transformations use reaction rules
See cross-referenceReaction System for transformation rules Language: WebGPU Shading Language (WGSL).Compilation: Shaders compiled at runtime by WebGPU driver.Validation: Browser provides shader compilation errors during development.Development Mode: Support shader hot-reloading for rapid iteration.Error Handling: Graceful fallback when shader compilation fails.Debugging: Use browser GPU debugging tools for shader profiling.GPU Timers: Measure individual pass execution times.Bandwidth Monitoring: Track texture read/write operations.Workgroup Tuning: Profile different workgroup sizes for optimal performance.]]>architecture/systems/physics/gpu-shaders.htmlarchitecture/systems/physics/gpu-shaders.mdFri, 07 Nov 2025 00:53:58 GMTSpell System).Impulse Method: Add velocity delta to current velocity (Δv applied once per spell contact).Velocity-Set Method: Directly replace velocity with spell-specified value.Mass Independence: Spell forces may ignore mass (TBD through spell design).
Details: See cross-referenceSpell System for spell shape mechanics and element combination rules.Force Sources: Each frame, objects accumulate forces from: Collision forces (from overlapping objects) Cohesion forces (from nearby objects within radius) Spell forces (from overlapping spell shapes) Summation: Forces summed using vector addition.Velocity Update: Net force applied to update velocity: v_new = v_old + (F_total / mass) * dtPosition Update: Updated velocity used to modify sub-grid offset.Determinism: All force calculations use fixed-point arithmetic for platform-independent results.Precision: Bit precision chosen to balance accuracy and GPU texture storage.Overflow Prevention: Force magnitudes clamped to prevent fixed-point overflow.
Details: See cross-referenceDeterminism for fixed-point implementation. Forces modify object velocities each frame
See cross-referenceMovement System for velocity and mass details Force calculations performed in "Apply Forces + Move" pass
See cross-referenceGPU Shaders for pipeline details Spell shapes provide force input from buffer Element types determine force application method
See cross-referenceSpell System for spell mechanics Collision vs Cohesion: Collision forces must overcome cohesion to allow object separation.Spell Dominance: Spell forces should be noticeable over ambient collision/cohesion forces.Combination Threshold: Objects approaching distance d should combine rather than bounce indefinitely.Playtesting Required: Force formulas will be refined through gameplay iteration.Adjustable Parameters: Force strengths and radii exposed as configuration values.Element Variation: Different spell elements may use different force strengths/types.Neighbor Limits: Two-layer range constraint keeps force calculations bounded.Parallel Computation: Force calculations fully parallelizable across objects in GPU.Early Termination: Skip force calculations for stationary objects with no nearby activity.]]>architecture/systems/physics/forces.htmlarchitecture/systems/physics/forces.mdFri, 07 Nov 2025 00:52:42 GMTForces).Spell Inputs: Spell elements can apply impulses or directly set velocities.Combinations: Merged objects receive mass-averaged velocity.Damping: Optional velocity damping to prevent perpetual motion (TBD through playtesting).Maximum Velocity: ~9.69 hex cells/second at 60fps based on two-layer force range guarantee.Gameplay Range: Typical gameplay velocities 2-6 cells/second, providing margin for force application.Range Guarantee: Two hex layers sufficient for all force interactions within speed limits.Type-Based: Each object type has an associated mass value.Layer Variation: Different layers may have different mass ranges (e.g., ground heavier than air).Gameplay Impact: Mass affects force response and combination outcomes.⚠️ NEEDS SPECIFICATION: Specific mass values for object types TBD through gameplay balancing.Force Response: Heavier objects accelerate less from the same applied force (F = ma).Collision Interaction: Mass ratio between colliding objects affects their relative force responses.Combination Averaging: When objects combine, velocities are mass-averaged to conserve momentum.Conservation: Total momentum preserved during combinations: m1*v1 + m2*v2 = m_combined * v_combinedOne-Per-Cell Guarantee: Ensures no hex cell ever contains more than one object.Gameplay Feature: Creates dynamic object fusion and reaction chains.Physics Stability: Prevents infinite force application from perpetually overlapping objects.Distance Threshold: Combination triggered when two objects approach closer than distance d.Merge Radius: All objects with centers within d of the combined center are included in the merge.Multi-Object Merges: Single combination can merge 3+ objects if they're all within radius.Velocity Averaging: Combined velocity is mass-weighted average of all merged objects.
Type Transformation: New object type determined by reaction rules applied to merged objects (see cross-referenceReaction System).Mass Assignment: New object mass based on its transformed type.Position: Combined object placed at mass-weighted centroid of merged objects.Position: Hex cell coordinates (using polar/cube system) Fixed-point offset (x,y) from cell center Velocity: Fixed-point vector (x,y) Stored in GPU texture alongside position Properties: Object type ID (for mass lookup and reactions) Mass value (may be stored or computed from type) Layer assignment (Ground/Object/Air) Texture Layout: Data packed efficiently for GPU texture storage and access patterns. Velocity modified by forces each frame
See cross-referenceForces for force types and calculations Movement calculations performed in GPU compute shaders
See cross-referenceGPU Shaders for pipeline details Objects check spell buffer for overlapping spell shapes Spell elements determine force application method
See cross-referenceSpell System for spell mechanics Combination types determined by reaction rules New object mass based on reaction-determined type
See cross-referenceReaction System for transformation rules Sub-grid offsets provide precise visual positioning Velocities available for motion blur and particle effects Ground Layer: Terrain foundation (dirt, stone, water) Object Layer: Interactive entities (rocks, trees, creatures, players) Air Layer: Gases and effects (fire, smoke, magic) ]]>architecture/systems/physics/movement-system.htmlarchitecture/systems/physics/movement-system.mdFri, 07 Nov 2025 00:51:51 GMTSpells and Runes for current architecture.GPU Processing: Shape evaluation (compute shaders) Element combination (shader computation) Rune delay countdown (GPU texture counters) Rune triggering and cleanup (multi-pass shaders) This document originally explored CPU-based spell processing for flexibility and ease of debugging. The decision was later revised to use GPU processing for consistency with physics and reaction systems, better performance at scale, and deterministic parallel evaluation.]]>architecture/systems/spells/cpu-architecture.htmlarchitecture/systems/spells/cpu-architecture.mdWed, 15 Oct 2025 00:03:58 GMTDeck Building for complete rules.Key Decisions: Spell selection from collection
Mana flower conversion to match deck composition (see cross-referenceMana System) Element focus vs diverse coverage ⚠️ NEEDS DESIGN: Curse system implementation details TBD.Risk/Reward: Cursed builds offer advantages with meaningful drawbacksOptional: Curses are optional - pure builds remain viableBuild Diversity: Support multiple viable build approaches⚠️ NEEDS SPECIFICATION: Curse selection mechanics Stacking rules (can multiple curses be combined?) Activation conditions and triggers Balancing approach between pure and cursed builds Integration with deck building and flower conversion ]]>architecture/systems/spells/customization.htmlarchitecture/systems/spells/customization.mdWed, 15 Oct 2025 00:03:53 GMTMana System) Validate deck meets minimum size Enter match with finalized configuration Immutable: Deck and flower configuration cannot change during match
Flower conversion details in cross-referenceMana System.Mechanic: Lose 2 flowers → gain 1 flower of chosen typePurpose: Specialize flower distribution to match deck's element compositionTrade-off: More specialized casting capability at cost of total flower capacityExamples: Fire-focused deck: Convert toward Chaos/Creation flowers Balanced deck: Use default 3-3-3-3-3-3 allocation
Element Access: All 26 elements accessible from game start (see cross-referenceElement System) No progression gate on element types Base, dual, and triple elements all available Spell Acquisition: ⚠️ NEEDS DESIGN - How players acquire spells for collection Spells are collectible (specific system TBD) Element availability ≠ spell availability Strategic depth from spell variety, not element unlocks ]]>architecture/systems/spells/deck-building.htmlarchitecture/systems/spells/deck-building.mdTue, 14 Oct 2025 23:57:55 GMTElement System: Order Flowers Chaos Flowers Creation Flowers Destruction Flowers Spirit Flowers Form Flowers Default Allocation: 3 of each type (18 total)Individual Tracking: Each flower has independent recharge state and cooldown.Duration: 3 turns per flowerIndividual Cooldowns: Each flower tracks its own timer independently.Recharge Behavior: ✅ Cast spell: Flowers recharge normally ✅ Load spell: Flowers recharge normally ✅ Movement: Flowers recharge normally ❌ Refresh pools: Flowers do NOT recharge (strategic penalty) Unlimited Regeneration: Flowers always regenerate. Never permanently lost during match.Flexible Costs: Spells require specific combinations and quantities of flower types.Examples: Basic Fire spell: 1 Chaos + 1 Creation Powerful Fire spell: 3 Chaos + 2 Creation Life spell: 1 Order + 1 Creation + 1 Spirit Validation: All required flowers must be available (not recharging) to cast spell.Cost-Power Relationship: Higher costs = more powerful spells. Specific costs TBD through playtesting.When: During deck building phase (before match starts)Operation: Lose 2 flowers → gain 1 flower of chosen typeIrreversible: Conversion affects starting flower configuration for that match.Purpose: Specialize flower distribution to match deck element composition.Trade-off: Increased element focus at cost of total capacity and flexibility.
cross-referenceElement System - Spell costs require combinations matching element structure (dual elements = 2 flower types, triple elements = 3 flower types)
cross-referenceSpells and Runes - Refresh action uniquely prevents flower recharge during cooldown
cross-referenceDeck Building - Flower conversion configured during deck construction]]>architecture/systems/spells/mana-system.htmlarchitecture/systems/spells/mana-system.mdTue, 14 Oct 2025 23:57:10 GMTdata-flow.md - implementation and effectiveness TBD ⚠️ data-flow.md is outdatedPurpose: Rule-based environmental transformations.Responsibilities: JSON rule compilation to optimized GPU shaders Competitive rule scoring and execution Environmental pattern matching (fire spreading, etc.) Optimization pipeline (specific implementation TBD) Dependencies: Core Engine (texture access), Build toolchainProcessing: GPU compute shaders with compiled rulesNote: The rule compilation pipeline allows simple code generation with sophisticated optimization. Alternative approaches welcome if simpler.Purpose: Visual display and user interface.Responsibilities: Multi-layer world rendering UI elements (mana flowers, spell hand) Visual effects and animations Camera and viewport management Dependencies: Core Engine (tile data access)Processing: GPU rendering pipelinePurpose: Development and debugging utilities.Responsibilities: Visual rule editor with grid-based interface Debug overlays and tile inspection Performance profiling and rule tracing Asset validation and testing tools Dependencies: All modules (for debugging access)
⚠️ PROPOSED ARCHITECTURE: A Deterministic Time-Sliced Execution approach has been proposed for variable timing and multiplayer synchronization. See cross-referencedata-flow.md for proposed pipeline details - implementation and validation TBD.
See cross-referencetile-storage.md for complete tile format and layer architecture details. Specific bit allocation TBD during implementation.
See cross-referenceperformance.md and individual system documentation for specific optimization strategies.
See cross-referencegameplay mechanics for complete gameplay mechanics and customization systems. Visual Editor: Grid-based rule design interface JSON Export: Human-readable rule definitions Compilation: Automatic shader generation and optimization Testing: Live rule testing and validation Integration: Hot-reload in development builds Tile Inspector: Real-time tile data examination Rule Tracer: Understand why specific rules activated Performance Overlay: Monitor frame timing and bottlenecks Determinism Validation: Verify identical execution across runs Tile Types: ~64 per layer (chosen to be comfortably under realistic limits)World Size: Fixed at initialization (no dynamic streaming)Flower Types: 6 (matching base elements)Casting Slots/Pools: Count TBD through playtesting (using 4 as example)Performance Degradation: Automated benchmarks prevent optimization regressionsRule Complexity: Visual editor prevents impossible shader compilationDeterminism: Strict execution ordering and integer-only mathematicsToolchain Stability: Containerized build environment for consistent results]]>architecture/general/overview.htmlarchitecture/general/overview.mdTue, 14 Oct 2025 23:52:30 GMTtile-storage.md for current architectural approach.Decision: Ground, Object, Air, Rune layers Rationale: Clean separation of different tile behaviors and interactions Alternative Considered: Single layer with type flags - rejected for complexityDecision: Dual texture approach for each layer Rationale: Prevents GPU read-after-write hazards and race conditions Trade-off: Double memory usage for synchronization safetyDecision: NOT IMPLEMENTING active region optimization Rationale: Implementation deemed too complex for expected benefit; planning for relatively few dormant areas in game design Alternative Sizes Considered: 32×32 tile chunks were originally proposed to balance GPU workgroup efficiency with memory overhead Status: All 32×32 chunk references throughout documentation are now outdatedDecision: JSON rules → GPU shaders via offline compilation Rationale: Move computational work to build time for runtime performance ⚠️ NOTE: Alternative approaches may be considered during implementationDecision: 26 elements organized in cube/octahedron geometric structure Rationale: Intuitive geometric opposition creates natural counter-play, component-level cancellation enables emergent combinations Structure: 6 base + 12 dual + 8 triple elements Alternative Considered: Smaller element set - rejected for strategic depthDecision: N slots + N pools system with three player actions (cast/load/refresh) Rationale: Creates meaningful decisions between immediate casting and deck cycling Trade-offs: Refresh action uniquely prevents flower recharge (strategic cost) Alternative Considered: Traditional hand system - rejected for limited strategic depthDecision: Abstract geometric primitives evaluated at runtime in GPU shaders Rationale: Perfect rotational symmetry, minimal memory, flexible design Alternative Considered: Pre-rendered texture system - rejected for memory cost and symmetry concernsDecision: Singleton format (no duplicates) with infinite reshuffle Rationale: Encourages spell variety, prevents deck depletion strategies Minimum Size: 6 × number of pools ensures sufficient variety Alternative Considered: Duplicate limits with deck depletion - rejected for complexityDecision: 6 flower types matching base elements with 3-turn recharge cycle Rationale: Direct correspondence with element system, individual tracking enables strategic timing Default Allocation: 3 of each type (18 total), unlimited regeneration Alternative Considered: 4-element system (fire/water/earth/air) - rejected for misalignment with element structureDecision: 2:1 flower conversion ratio during deck building Rationale: Enables element specialization at meaningful cost (total capacity reduction) Alternative Considered: No conversion - rejected for limited deck customizationDecision: ~64 tile types per layer Rationale: Chosen to be comfortably under realistic GPU and memory limits Constraint: Leaves room for expansion without architectural changesDecision: Identical inputs must produce identical outputs Rationale: Essential for fair PvP gameplay Implementation: Integer-only mathematics, simultaneous single-read/single-write GPU passes with deterministic internal rules ⚠️ CHALLENGE: GPU thread execution order is not inherently deterministic - Addressed through simultaneous read/write pass architectureDecision: Fixed world size at initialization Rationale: Avoids dynamic streaming complexity Trade-off: Limits map variety for implementation simplicityDecision: Grid-based rule design interface planned Rationale: Simplifies rule creation and prevents impossible shader compilation Status: Design planned, implementation TBDDecision: Use containerized build for consistent results Rationale: Ensures deterministic shader compilation across development environments ⚠️ STATUS: Implementation approach needs specification⚠️ Major Design Decisions Still Needed: Frame Rate Coordination: How to handle different update frequencies between physics (60 FPS) and reactions (potentially lower)? Rule Compilation Pipeline: Exact toolchain and optimization steps? World Size Limits: Performance testing needed to determine optimal map dimensions? Build System Integration: How rule compilation integrates with main build process? Spell System TBD: Number of Casting Slots/Pools: Using 4 as example, optimal count requires playtesting Spell Shape Primitives: Which geometric primitives to support for spell design Void Rune Effects: Powerful secret mechanic effects need design Single Element Rune Effects: Beyond mana recharge, additional effects TBD Curse System Implementation: Mechanics, stacking rules, balancing approach Spell Acquisition System: How players unlock/collect spells ]]>architecture/general/technical-decisions.htmlarchitecture/general/technical-decisions.mdTue, 14 Oct 2025 23:52:00 GMTarchitecture/general/performance.htmlarchitecture/general/performance.mdMon, 13 Oct 2025 23:15:21 GMTData Flow Architecture - Parent pipeline architecture
cross-referenceVariable Timing System - Time slice scheduling integration
cross-referencePerformance Strategy - Optimization approaches with determinism constraints ⚠️ NEEDS IMPLEMENTATION: GPU compute shader templates for deterministic processing Cross-platform validation test suite Performance benchmarking of spatial ordering overhead ]]>architecture/general/deterministic-execution.htmlarchitecture/general/deterministic-execution.mdMon, 13 Oct 2025 23:10:27 GMTarchitecture/systems/core/active-regions.htmlarchitecture/systems/core/active-regions.mdMon, 13 Oct 2025 20:57:42 GMTTile Storage System - Bit-packing format and layer organization
Texture Management - GPU texture coordination and ping-ponging
Active Regions - Chunk-based processing optimization
API Reference - Classes and integration points Ground Layer: Terrain foundation (dirt, stone, water) Object Layer: Interactive entities (rocks, trees, creatures, players) Air Layer: Gases and effects (fire, smoke, magic) Rune Layer: Spell-placed magical effects (temporary) Active Region System: Only process chunks with changing tiles Texture Ping-Ponging: Prevents GPU read-after-write hazards Bit-Packed Storage: 32-bit tile representation Chunk-Based Processing: 32×32 tile regions Spell System: Writes rune data to rune layer textures Physics Engine: Reads/writes velocity data via texture pairs Reaction Engine: Processes transformation rules on tile data Renderer: Provides read-only access to current tile states for display Game Logic: Exposes tile query API for validation and state checking WebGPU API: Required for texture management and GPU compute coordination ]]>architecture/systems/core/core.htmlarchitecture/systems/core/core.mdMon, 13 Oct 2025 20:57:42 GMTarchitecture/systems/core/api-reference.htmlarchitecture/systems/core/api-reference.mdMon, 13 Oct 2025 20:57:42 GMTarchitecture/systems/core/tile-storage.htmlarchitecture/systems/core/tile-storage.mdMon, 13 Oct 2025 20:57:42 GMTarchitecture/systems/gpu/gpu.htmlarchitecture/systems/gpu/gpu.mdMon, 13 Oct 2025 20:57:42 GMTlegacy/v1-data-strategies.htmllegacy/v1-data-strategies.mdMon, 13 Oct 2025 20:57:42 GMTlegacy/v1-gpu-patterns.htmllegacy/v1-gpu-patterns.mdMon, 13 Oct 2025 20:57:42 GMTlegacy/v1-reference.htmllegacy/v1-reference.mdMon, 13 Oct 2025 20:57:42 GMTlegacy/v1-visual-effects.htmllegacy/v1-visual-effects.mdMon, 13 Oct 2025 20:57:42 GMTTask List for automated queries that collect and organize these items across all documentation. Use status to track document maturity through its lifecycle Apply tags for broad categorization (multiple tags allowed) Subcategorize todo items to help with task filtering and prioritization Subcategorize warnings to identify types of concerns at a glance Update status as documents progress from draft → proposed → approved → implemented Mark documents as outdated when code diverges from documentation The goal is that readers can efficiently find exactly what they need without encountering duplicate or outdated information.]]>development/documentation_structure.htmldevelopment/DOCUMENTATION_STRUCTURE.mdMon, 13 Oct 2025 19:47:30 GMTV1 Rules Engine Reference - Mathematical algorithms and GPU optimization from rules system
V1 Environmental Examples - Terrain interaction patterns and emergent behaviors
V1 GPU Optimization Patterns - Compute shader strategies and memory management
V1 Visual Effects - Rendering techniques and material systems
V1 Data Packing Strategies - Data organization and bit-packing techniques Reference material extracted from V1 codebase to ensure V2 developers understand the complexity and sophistication of systems being replaced. ]]>legacy/legacy.htmllegacy/legacy.mdMon, 13 Oct 2025 18:35:06 GMTlegacy/v1-environmental-examples.htmllegacy/v1-environmental-examples.mdMon, 13 Oct 2025 18:35:06 GMTCore Mechanics - Victory conditions, timing, and elimination rules Genre: Real-time PvP grid-based spellcasting game Victory: Last player standing (avatar tile elimination) Core Loop: Cast spells → Place runes → Transform environment → Tactical positioningNon-Turn-Based: Continuous simulation without traditional turns Pre-Planning: Players can queue actions in advance Dynamic Speed: Movement controlled by time delays between position updatesReactive World: Spells transform terrain according to rule-based systems Terrain Types: Different tile types provide tactical advantages Evolving World: Continuous world changes create evolving opportunitiesNo Scarcity: Unlimited mana regeneration - focus on timing over conservation Recharge Timing: 3-turn recharge cycle provides natural rhythm Allocation Choice: Specialization vs. flexibility in mana allocation]]>gameplay/gameplay.htmlgameplay/gameplay.mdMon, 13 Oct 2025 18:35:06 GMTdevelopment/building-documentation.htmldevelopment/building-documentation.mdMon, 13 Oct 2025 18:35:06 GMTarchitecture/systems/ui/ui.htmlarchitecture/systems/ui/ui.mdMon, 13 Oct 2025 18:35:06 GMTdevelopment/development_principles.htmldevelopment/DEVELOPMENT_PRINCIPLES.mdMon, 13 Oct 2025 18:35:06 GMTarchitecture/systems/tools/tools.htmlarchitecture/systems/tools/tools.mdMon, 13 Oct 2025 18:35:06 GMTarchitecture/systems/rendering/rendering.htmlarchitecture/systems/rendering/rendering.mdMon, 13 Oct 2025 18:35:06 GMTRule Compilation - JSON to GPU shader pipeline
Rule System - Competitive scoring model and execution
Visual Editor - Development tools and rule creation interface
Examples - Sample rules and common patterns Problem: Multiple rules may apply to the same tile simultaneously. Solution: Competitive evaluation where highest-scoring rule wins.Design Philosophy: Move all possible computational work to build time for minimal runtime overhead.Lower frequency than physics: Reactions may run less frequently for performance. ⚠️ Challenge: Coordination with physics timing is a major technical issue to solve. Core Engine: Required for texture access and coordination Build Toolchain: Rule compilation requires build-time processing ]]>architecture/systems/reactions/reactions.htmlarchitecture/systems/reactions/reactions.mdMon, 13 Oct 2025 18:35:06 GMTarchitecture/systems/reactions/rule-compilation.htmlarchitecture/systems/reactions/rule-compilation.mdMon, 13 Oct 2025 18:35:06 GMTState Management for complete integration details.Single Engine: Same game engine used for single-player and multiplayer prediction.Deterministic Execution: Time-sliced pipeline ensures identical client/server results.Automatic State Management: Built-in snapshots and rollback through unified state system.Frame Synchronization: Time slice alignment with server for precise synchronization. Local state prediction using identical simulation logic Server state comparison with automatic mismrediction detection Rollback and re-execution through unified state management Ghost simulation for action queue visualization Purpose: Runs identical simulation logic for local prediction.Components: Same GPU compute shaders as server Physics and reaction processing Tile state management with active regions Deterministic frame execution pipeline Key Differences: Operates on unconfirmed inputs Generates visual output during prediction Maintains rollback state history Handles prediction correction smoothly Confirmed States: Server-validated game states stored every 5 frames Prediction States: Local simulation results with input applied Rollback Threshold: Maximum 10 frames (167ms at 60 FPS) Server State Reception: Authoritative state update arrives Local Comparison: Compare with predicted state at same frame Divergence Analysis: Identify significant differences Rollback Decision: Determine if correction is necessary State Restoration: Revert to last confirmed server state Input Replay: Re-apply all inputs since that frame Simulation Catch-up: Run physics/reactions to current frame Visual Interpolation: Smooth transition to corrected state Own Actions Only: Predict consequences of local player inputs Physics Prediction: Tile movement and basic collisions Spell Effects: Immediate visual feedback for cast spells Avoid Complex Rules: Don't predict environmental transformationsAll Player Actions: Predict other players' likely actions Rule Interactions: Attempt complex environmental predictions Higher Rollback Risk: More frequent corrections needed Better Responsiveness: Smoother gameplay when predictions succeedNetwork Quality Based: Adjust strategy based on connection stability Misprediction History: Learn from previous prediction accuracy Dynamic Threshold: Modify rollback sensitivity based on gameplay contextinterface PredictedInput { frameNumber: number; playerId: string; inputData: PlayerInput; timestamp: number; confirmed: boolean; } Local Input Capture: Player action registration Immediate Prediction: Apply to local simulation instantly Server Transmission: Send input with frame number Confirmation Tracking: Mark inputs as confirmed when server acknowledges History Cleanup: Remove old confirmed inputs from buffer Interpolation: Smooth transition between predicted and actual states Temporal Blending: Gradual adjustment over multiple frames Priority System: Prioritize corrections for player-controlled entitiesOptimistic Updates: Show immediate response to player actions Uncertainty Indicators: Visual cues for unconfirmed actions Rollback Masking: Hide jarring corrections with effectsSpatial Boundaries: Only predict within player's view range Temporal Limits: Maximum prediction window of 10 frames Complexity Filtering: Skip expensive calculations during predictionState Compression: Efficient storage of rollback snapshots Garbage Collection: Automatic cleanup of old prediction data GPU Resource Sharing: Reuse textures between prediction and renderingLatency Measurement: Dynamic adjustment of prediction window Quality Scaling: Reduce prediction complexity on slow connections Fallback Mode: Disable prediction on extremely poor connectionsDesync Recovery: Full state resynchronization when prediction fails Input Loss: Request missing inputs from server State Corruption: Fallback to last known good stateConnection Loss: Maintain prediction until reconnection High Latency: Extend prediction window with quality reduction Packet Loss: Request state recovery from serverFrame Drops: Reduce prediction complexity automatically Memory Pressure: Cleanup old snapshots more aggressively GPU Issues: Fallback to CPU-only prediction if necessaryThis system provides responsive gameplay while maintaining competitive integrity through authoritative server validation.]]>architecture/systems/multiplayer/client-prediction.htmlarchitecture/systems/multiplayer/client-prediction.mdMon, 13 Oct 2025 18:35:06 GMTarchitecture/systems/core/texture-management.htmlarchitecture/systems/core/texture-management.mdMon, 13 Oct 2025 18:35:06 GMTarchitecture/systems/config/config.htmlarchitecture/systems/config/config.mdMon, 13 Oct 2025 18:35:06 GMTData Flow Architecture - Parent pipeline architecture
cross-referenceDeterministic Execution - Execution order and consistency
cross-referenceState Management - Integration with state snapshots ⚠️ NEEDS TEAM DISCUSSION: Optimal slice count (current proposal: 8 slices per frame) Speed multiplier ranges (current proposal: 0.1x to 10x) Ghost prediction complexity vs performance trade-offs ⚠️ NEEDS IMPLEMENTATION: Detailed performance benchmarking of time slice overhead Integration testing with existing Core Engine texture management Multiplayer synchronization validation ]]>architecture/general/variable-timing.htmlarchitecture/general/variable-timing.mdMon, 13 Oct 2025 18:35:06 GMTData Flow Architecture - Parent pipeline architecture
cross-referenceVariable Timing System - Integration with action scheduling
cross-referenceRenderer System - Visual rendering integration ⚠️ NEEDS TEAM DISCUSSION: Default simulation complexity level (minimal/basic/detailed) Ghost prediction accuracy vs performance trade-offs Visual design for ghost representation (transparency, colors, indicators) ⚠️ NEEDS IMPLEMENTATION: Performance benchmarking of different complexity levels User experience testing of ghost feedback effectiveness Integration testing with action queue and timing systems ]]>architecture/general/ghost-simulation.htmlarchitecture/general/ghost-simulation.mdMon, 13 Oct 2025 18:35:06 GMT