Blood Visual (Stains, World Feedback, HUD)

Authoritative project content

Blood is both visual state and an infection-risk input — [CONFIRMED]. Every 10 real-time minutes, the server evaluates infection probability from immunity and blood on the character and worn equipment.

Related: 03-Combat-System.md, 06-Inventory-and-Items.md, 08-Character-Creation.md, 09-Weapon-Customization.md, 11-Wetness-and-Rain.md, ../03-Enemies/01-Zombie-Design.md, ../03-Enemies/02-Boss-Zombies.md, ../06-Art-Audio/01-Art-Direction-and-MetaHuman.md.

Dirt / fouling is cancelled (no dirt meter, no workbench cleaning, no jam/spread-from-dirt). Use still reduces durability. See 09-Weapon-Customization.md.

Layers — [CONFIRMED]

Both exist (they are not alternatives):

Blood color is one palette for all living targets (player, zombie, boss, animal). Do not author separate human vs zombie blood colors unless that decision is reopened.

Mesh stain — material contract — [CONFIRMED]

• Approach: mask on the existing material, not a Material Layer Blend stack.
• Control: a single scalar BloodAmount in 0–1 per stained object (one value for the whole item/mesh, including multi-slot materials).
• Mask: authored per mesh. Shared/procedural masks are not the v1 contract.
• MID applies that scalar to the mask. Exact parameter names are [TBD] (technical art).
• If a mesh has no blood mask (or materials do not expose the stain path), it shows no blood. Missing mask is not a ship blocker for that asset, but the pipeline applies to all future content in this system.
• New melee / clothing / body content is expected to follow this pipeline; unmasked pieces simply stay clean-looking.

What can stain (attacker) — [CONFIRMED]

Stains the thing that scored a melee hit, when that hit connects and deals damage to a living target.

Counts:

• Any equipped item that can perform a melee hit (melee weapons, tools, building hammer, etc.).
• A firearm used as a melee strike (butt / bayonet / similar) — the gun mesh stains.
• Unarmed punch: skin of the hands if no gloves are worn; gloves only (not hand skin) if gloves are worn.
• Kick: shoes.

Does not count:

• Thrown melee / thrown items.
• Hits on structures, walls, doors, or other non-living props (nothing to bleed).
• Block / parry — the attacker's weapon does not stain from being blocked.

Ranged gunfire does not stain the firearm. It can still stain the victim (see below).

What can stain (victim and bystanders-on-body) — [CONFIRMED]

When a living target takes damaging hits (melee, firearms, explosives, or any other damage that actually deals damage):

• Their outer worn clothing can stain. Which slot is “outer” is [TBD] until clothing layers are designed; do not implement a layer-priority table yet.
• Items in inventory that are not worn do not stain.
• Hair and skin stain. That BloodAmount lives on the character/pawn, not on an item. Changing clothes does not clear body/hair blood.
• Eyes do not receive a mesh stain.
• Zombies and bosses use the same mesh-stain contract on their bodies (per-mesh mask + BloodAmount).
• Animals use the same living-target rules.

Dual state: item vs character — [CONFIRMED]

Both can be stained at once (e.g. bloody shirt item + bloody skin/hair on the pawn).

Accumulation — [CONFIRMED] rules, numbers [TBD]

• Amount added scales with damage dealt (attacker gear) or damage taken (victim clothes/body). Do not invent a formula, coefficient, or curve in code or docs.
• There is a ceiling (visual saturates; treat the scalar cap as 1.0 unless a different cap is decided later).
• Stains ease in (not a binary first-hit full coat).
• Stains do not decay until a wash system exists.

Wash — [CONFIRMED] intent, not this slice

Workbench cleaning of dirt/blood is cut.

Future wash sources (not built in the visual-pipeline slice):

• Faucet
• Water source
• Rain — [CONFIRMED] to reduce blood over time while exposed

Rain exposure reduces BloodAmount. The exact wash rate, faucet/water-source interaction, and whether manual washing is channeled remain [TBD]. WetAmount remains an independent scalar.

Networking, inspect, save — [CONFIRMED]

• Other players must see mesh stains (weapons, worn clothes, hair/skin, zombies/bosses).
• Mesh BloodAmount on items is instance state: world drops, loot, and workbench 3D inspect show the stain.
• Item and player character body/hair blood persist in the save record.
• Whether AI blood (zombie/boss/animal) is written into world persistence or only lives on the actor until despawn is [TBD]. [CONFIRMED 2026-09-14] P07 does not persist AI blood.

HUD overlay is local-only and is not replicated.

Local HUD overlay — [CONFIRMED] existence, tuning [TBD]

• Blood marks on the local player's screen, then fade over time.
• Replaces staining the eye mesh.
• Duration, intensity vs damage, and exactly which events spawn it (incoming damage, camera-facing splatter, melee swing, combinations) are [TBD]. Do not copy a third-party vignette curve.

Gameplay — [CONFIRMED] infection risk

Low immunity and higher BloodAmount on the character or worn equipment increase infection probability. The server rolls once every 10 real-time minutes. The probability curve, thresholds, contribution of each stained item, and treatment rules remain [TBD]. Blood does not affect stealth or AI senses unless separately approved.

Pipeline ownership — [CONFIRMED]

• Spec first; mesh masks and material wiring follow the contract above.
• This is a game-wide pipeline, not a one-weapon prototype. Content without a mask simply does not show the stain.

Open questions still [TBD]

Do not implement as if decided:

• Clothing outer-layer resolution.
• BloodAmount gain formula and easing.
• Blood-mask authoring details beyond the confirmed BloodAmount scalar and BloodMask texture name.
• HUD overlay triggers, duration, and intensity.
• Rain wash rate plus faucet/water-source implementation.
• AI blood persistence across server restart. P07 does not persist it.
• World splatter/decal art direction (materials, lifetime, pooling) beyond “this layer exists.”
• Infection probability curve, thresholds, item contribution, and treatment.