Type transformations triggered by object merging, environmental neighbor patterns, and timers.

The reaction system determines how objects transform when they interact. Primarily handles environmental reactions (neighbor-based patterns) but also provides type transformations during object merging. Reactions are tightly integrated with physics, running every physics frame within the same GPU passes.

Note: Spell-triggered transformations are handled separately - see cross-referenceSpell 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_type

Multiple 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:

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:

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.