Real-Time Hybrid Blood Simulation for 2.5D Environments

A completed technical study of how ballistic droplets, persistent surface deposits, accumulation, dripping, puddling, transfer, smearing, and drying can be approximated efficiently in an orthographic 2.5D presentation backed by a mathematically three-dimensional world.

Current Status

The study remains complete for its validated representation and geometry scope. Most deposited wall blood stays stationary. Fresh qualifying impacts may form one or two short surface streaks. Phase 8 additionally allows a sufficiently wet dense fresh impact to nominate the existing full runner immediately; that runner can continue to the gravity-facing edge, mature into a hanging bead, and enter the world-droplet solver. Concentrated blood on upward surfaces redistributes through the conservative radial pool pass.

Research Problem

How can a large quantity of blood remain spatially coherent while switching between world-space ballistic motion and persistent surface-space state, without requiring a full three-dimensional fluid simulation?

The current method treats blood as 3D only while free in the world. Once attached, it becomes a sparse two-dimensional material field anchored to a real three-dimensional surface.

World Model

X = room width
Y = room depth
Z = height

Droplets, gravity, collision, objects, and surface transforms are defined in XYZ. Camera projection is presentation-only. Phase 5 defaults to an isometric orthographic angle to make that separation visually obvious.

Surface Contract

The final surface type is a finite planar rectangle with an origin, local U/V basis, normal, and dimensions.

Persistent blood is indexed in local U/V coordinates. Exact shared rectangular edges provide topology for wrapping and dynamic continuation. Arbitrary polygonal and deforming blood-bearing meshes were not validated and remain outside the frozen scope.

Hybrid Representation

impact event
    ↓
procedural morphology
    ↓
sparse persistent surface field
    ↓
selected active drip / pool behavior
    ↓
unsupported endpoint
    ↓
hanging tip
    ↓
XYZ WorldDroplet
    ↓
new impact event

Overlapping deposits merge through field amount instead of stacking transparent decals. Wetness, age, and frozen state remain attached to the same persistent cells.

Phase 3 - Broad Gravity Flow

Phase 3 proved that projected gravity, puddling, unsupported detachment, and world-space redeposition could share one field representation. It also exposed an important failure: allowing nearly every wet wall cell to advect made large portions of a splat slide together and produced dense vertical curtains.

Phase 4 - Sparse Channels and Transfer

Phase 4 corrected broad advection by selecting a small number of wet local peaks as active sources. Channels move limited packets, leave residue, respect regional cooldowns, transfer through exact topology or nearby support, and detach only at unsupported edges. Contact pickup and directional smearing were added without creating a separate footprint system.

Phase 5 - Drip Maturation and Radial Pooling

Phase 5 keeps the Phase 4 transfer rules but refines the most visible interaction and liquid behaviors. Patch v0.6.1 corrected impact authoring, source reliability, pooling speed, and drying speed. Patch v0.6.2 then narrows source creation to connected dense regions and separates mist, body, and dense appearance.

Drag-Directed Splash Tool

Press on a visible surface, drag in the desired splash direction, and release. The start point is raycast onto the scene. The drag vector is projected onto that surface's screen-space U/V axes so direction remains surface-local even under the isometric camera. Drag length maps to impact speed, with a low-force floor and the existing speed cap. A short click retains the old nominal stamp.

Dense-Region Drip Outlets

Patch v0.6.2 replaces broad per-cell source competition with connected dense-region analysis. Cells must reach the dense amount and wetness thresholds before they can participate in source selection. Touching dense cells are grouped with eight-neighbor connectivity, then evaluated as one region.

Only candidates on the gravity-facing lower portion of that region are scored. Amount, wetness, downhill contrast, local peak strength, and lower-edge position determine the ordering. One or two well-spaced outlets may survive from a component, while the surface-wide cap remains bounded. Mist and body material can never start a new drip.

Once selected, channels still use projected world gravity. On a vertical wall this means movement toward lower world Z, independent of camera angle.

Mist, Body, and Dense Appearance

The simulation field remains continuous, but rendering now classifies visible material into three zones. Mist stays faint and decorative. Body material is substantially more opaque so thin runs remain readable. Dense material becomes darker red and nearly opaque, producing a heavy visual core closer to the reference behavior.

Hanging tips are also darkened so a drip visually inherits the weight of the dense region that produced it.

Hanging Drip Tips

A newly detached unsupported packet is intercepted before world-space free flight. It becomes a short-lived hanging bead that retains the eventual droplet's position, volume, radius, seed, and release velocity. The displayed bead grows through a deterministic maturation interval before release.

This introduces a readable surface-to-air transition without replacing the proven ballistic solver.

Radial Floor Pools

Upward-facing wet cells inspect a wider circular neighborhood. Patch v0.6.1 lowers the default radial rate from 1.35 to 0.22 and reduces the maximum per-step movable fraction from 14% to 8%, so a pool grows visibly instead of blooming outward immediately. Lower-pressure cells receive conservatively bounded transfers weighted by Euclidean distance. Small seeded variation perturbs the edge so the target is rounded rather than mathematically perfect.

Support transfers, landed droplets, direct impacts, and contact smears all continue to feed the same field. Repeated drops therefore enlarge and merge persistent pools.

Isometric Camera Stress

The Phase 5 lab defaults to approximately 45 degrees yaw and 35.264 degrees pitch with orthographic projection. Yaw and pitch remain adjustable in the property panel.

This is intentionally a presentation experiment rather than a new simulation mode. The field, gravity, topology, and droplet behavior receive no camera input.

E5 Controlled Sweep

results/phase5/E5_drip_pooling.csv

The 45-second export records wet and frozen cells, active drip sources, hanging tips, active world droplets, puddle cells, channel movement, radial pool movement, support transfers, detachments, and landings.

Phase 6 - Sparse Drips and Surface-Field Optimization

The v0.7.0 ribbon checkpoint is preserved by its release, but v0.7.1 supersedes the active ribbon motion. Phase 5 still selects dense gravity-facing outlets. Phase 6.1 converts one accepted outlet into one localized reservoir runner, leaving the parent stain substantially stationary.

Single-Reservoir Runner

A runner gathers a bounded amount from a small dense neighborhood, advances along projected surface gravity, and spends a distance-aware fraction of that reservoir on a narrow persistent trail. A six-cell source neighborhood is marked as seeded for the current session, preventing repeated runners from the same dense region. At the gravity-facing edge the remaining reserve becomes the existing hanging-tip and world-droplet path.

Active-Field Performance Pass

Phase 6 now uses 32 field cells per world unit instead of 42. The renderer walks occupied sparse cells directly and no longer constructs a three-by-three expanded candidate hash set every frame. Pool relaxation runs at 30 Hz, drying/freezing at 20 Hz, and puddle statistics at 4 Hz while runner and world-droplet motion remain on the 120 Hz fixed substep.

Superseded Ribbon Checkpoint

BS-012 and v0.7.0 tested lateral ribbon widening. The release remains preserved, but active ribbon redistribution is superseded by BS-014 because the broader motion made too much of the stain appear mobile at once.

Halo Suppression

A visible render cell must now contain actual persistent blood and also pass the smoothed visibility threshold. This keeps smoothing inside the blood shape while preventing empty cells around a dense stain from becoming pale translucent borders.

Surface Response

The Phase 6 material scaffold assigns simple response multipliers by surface kind. Room walls use the baseline, while box surfaces use slightly different runner speed and raw render cutoffs. A complete roughness, porosity, and absorption model was not promoted into the frozen reference.

Phase 7 - Final Hybrid Reference

Phase 7 does not replace the Phase 6 runner. It adds a second, smaller drip behavior for fresh splatters and then freezes the architecture. A qualifying wall impact may nominate zero, one, or two short streaks from nearby wet body-or-dense cells.

Sparse Impact Drip Streaks

Each streak gathers a bounded reservoir while leaving at least 82 percent of each contributing cell or the body threshold. It advances under projected world gravity. In the v0.8.1 readability patch, a normal step writes a mass-conserving three-cell ribbon with most material in the center and enough real side-cell mass to remain visible through the raw-cell cutoff. Strong streaks may briefly use a wider source-proximal profile. Most travel remains straight, with sparse deterministic one-cell lateral wiggle.

Impact streaks never become airborne. The Phase 6 full runner remains the distinct path for a bead that reaches a surface edge, hangs, and becomes a world-space droplet.

E7 Final Scale Sweep

results/phase7/E7_final_reference.csv

The preserved Phase 7 export begins with sixteen deterministic impacts and simulates 45 seconds. It records wet and frozen cells, allocated sparse tiles, estimated field bytes, total attached amount, full runners, short streaks, hanging tips, airborne droplets, puddle cells, runner and streak movement, maintenance passes, detachments, and landings.

Phase 8 - Gravity Rivulet Extension

Phase 8 does not add another fluid representation. After a fresh impact is deposited, a deterministic local search may promote one sufficiently wet dense cell into the existing Phase 6 full-runner path immediately. Mist, body-only material, frozen cells, already-seeded neighborhoods and nearby active runners remain ineligible.

The promoted runner uses the existing bounded reservoir and distance-to-edge trail budget, moves under projected world gravity, leaves a persistent narrow runoff trail, becomes a hanging tip at the surface edge, and then enters the existing XYZ droplet solver. Swept collision determines the first valid lower surface for redeposition. Phase 7 short impact streaks remain unchanged and may coexist with the rivulet.

E8 Rivulet Sweep

results/phase8/E8_rivulet_reference.csv

E8 repeats the multi-impact reference run with immediate long-rivulet nomination enabled while retaining the same sparse-field, runner, hanging-tip, droplet, pooling, drying and performance accounting.

Experiments

Measurements

The native suite covers Phase 8 rivulet nomination plus source sparsity, stationary mass retention, support transfer, detachment, near-floor collision, connected transfer, contact smearing, hanging-tip staging, radial pool symmetry, opacity ordering, runner conservation, maintenance-rate bounds, short-streak conservation, deterministic streak origins and lengths, downward streak travel, transient caps, and finite state through a ten-second fixed-step run. E7 preserves the frozen Phase 7 scale record; E8 adds the same multi-impact accounting with immediate long-rivulet nomination enabled.

Failed Approaches

Field-wide wall advection

Phase 3 allowed too many wet cells to move under gravity. Large splats visibly collapsed downward. The approach is preserved as BS-005 and superseded by sparse source selection.

Four-neighbor floor spread

The earliest pressure pass produced diamond-shaped puddles. Phase 4 expanded to eight neighbors. Phase 5 uses a wider radial neighborhood.

Immediate unsupported detachment

Phase 4's endpoint-to-particle transition was functional but visually abrupt. Phase 5 adds a short hanging stage while preserving the same world-droplet solver.

Promotion Rule

A new blood behavior is not treated as part of the eventual reference architecture simply because it looks better in one scene. Promotion requires deterministic behavior, a preserved baseline, automated conservation or geometry checks where applicable, human visual review, documented failure conditions, and no dependence on camera-space state.

Completion Boundary

The Phase 7 reference remains frozen. Phase 8 is a bounded source-nomination extension inside the same validated static-planar-surface scope. Future work on arbitrary/deforming meshes, full fluid puddles, aerodynamic breakup, generalized surface materials, or richer rigid-body transfer should still begin as a separate study rather than expanding this extension into a general fluid solver.

Current Implementation

1. Convert a surface hit into local impact parameters.
2. Generate deterministic procedural stain morphology.
3. Merge the deposit into sparse surface-field tiles.
4. For a qualifying dense wet impact, optionally nominate one immediate long rivulet.
5. Optionally seed zero to two preserved Phase 7 short-streak reservoirs.
6. Advance short streaks under projected gravity and deposit mass-conserving three-cell trails.
7. Periodically discover any remaining dense gravity-facing full-runner outlet candidates.
8. Convert an unseeded dense outlet into the bounded full-runner representation.
9. Advance the runner under projected gravity and deposit a narrow persistent trail.
10. Convert the runner reserve into a hanging tip at the gravity-facing edge.
11. Release matured tips into the XYZ droplet solver.
12. Sweep droplets against world surfaces and redeposit on the first valid lower surface.
13. Redistribute concentrated upward-surface blood through a 30 Hz radial pool pass.
14. Apply drying/freezing at 20 Hz and puddle statistics at 4 Hz.
15. Apply optional contact pickup and directional smearing.
16. Render occupied sparse cells directly, independently of camera orientation.

Architecture

phases/
├── phase0/
├── phase1/
├── phase2/
├── phase3/
├── phase4/
├── phase5/
├── phase6/
├── phase7/   frozen reference
└── phase8/
    ├── main.cpp
    ├── phase8_dynamics.hpp
    └── test_phase8.cpp

Phase 8 inherits the frozen Phase 7 short-streak behavior and the optimized Phase 6 full-runner lifecycle. It changes only how a fresh dense impact may enter that runner path. Earlier phase directories remain buildable research checkpoints.

Repository

nm-pm/
└── projects/
    └── blood-simulation/
        ├── index.html
        ├── DOCUMENTATION.html
        ├── README.md
        ├── ARCHITECTURE.md
        ├── RELEASES.md
        ├── CMakeLists.txt
        ├── phases/
        ├── experiments/
        ├── figures/
        └── assets/

Every implementation phase preserves its earlier harness and updates code, tests, durable experiments, documentation, and release metadata in the same phase commit.

AI Transparency

Generative AI was used extensively as a development tool for implementation, debugging, mathematical exploration, and documentation support. The study direction, constraints, testing, visual review, and acceptance or rejection of approaches were decided by the human researcher.

Frozen Limitations

• Radial pools remain a pressure-relaxation approximation rather than a free-surface height solver.
• Validated surface topology remains rectangular and exact-edge based.
• Contact transfer remains simplified and primarily floor-oriented.
• Surface roughness, porosity, and absorption are not generalized physical material parameters.
• World droplets remain simple spherical packets without aerodynamic breakup.
• Arbitrary polygonal, moving, and deforming blood-bearing surfaces remain outside the validated method.

These are documented extension points, not unfinished requirements of the completed Phase 7 reference.

Research Log

Version History