ZOA VFX

SurfaceClassResolver walks four steps and the first hit wins. An explicit HitImpactContext.SurfaceOverride short-circuits everything, which is how a caller that already knows the answer skips the work: an AI damage receiver hitting a known body part supplies the Flesh definition directly.

Next comes the explicit marker. GetComponentInParent<SurfaceMarker> walks from the hit collider up through its parents and takes the nearest marker with a non-null Surface. Because it is the nearest that wins, a fine-grained marker on a head bone overrides a coarse one on the rig root, and dropping a marker on a prefab root gives the whole prefab a default with per-child exceptions.

Third is the GameObject tag. The resolver walks the same transform chain, asking the registry to match each ancestor's tag. This exists because tagged rigs usually carry the tag on the root only, and routing "Player" and "Enemy" straight to Flesh is far cheaper than authoring a SurfaceMarker on every body collider. Unity's "Untagged" default is explicitly rejected as a match so an accidentally untagged collider falls through rather than claiming whichever surface happens to list it.

Fourth is material name matching. The resolver finds a Renderer on the collider or the nearest parent, reads sharedMaterials so no instance material is created, and asks the registry which surface claims each material name. Matching is a case-insensitive substring check, so a Concrete surface listing "concrete", "rebar", and "rock" claims a material named Wall_Concrete_02.

If all four miss, the registry's Default catches it. The resolver only returns null when the registry itself is empty or no default was set, which in practice means a test fixture.

A concrete wall should not react identically to a sniper slug and to one pellet of a shotgun spread. HitImpactContext carries an ImpactClassId, and SurfaceClassDefinition holds a sparse list of ImpactClassOverride rows keyed by that id. TryGetOverride does a case-insensitive lookup and returns null when the surface has no row, which is the signal to use its defaults.

The ids are strings rather than an enum. ImpactClass names the seven canonical values, bullet, buckshot, slug, beam, plasma, explosive, and melee, but a project that adds a bow-and-arrow archetype just types a new id. An enum would force every consumer to recompile against the package.

Overrides are sparse in both directions. A row can swap the decal prefab, the particle prefab, and the audio cue, and it scales the surface's authored size and lifetime through DecalSizeMultiplier and DecalLifetimeMultiplier, both defaulting to 1. Any field left null or at its default falls through to the surface, so a row that only wants a bigger crater sets one multiplier and nothing else.

HitDecalService.Spawn resolves the surface, looks up the impact-class override, and folds the two into a single set of choices: decal prefab, particle prefab, audio cue, size, and lifetime. A null resolver, a null pool service, or an unresolved surface each ends the call quietly rather than throwing into the firing path.

The decal spawns with Quaternion.LookRotation of the negated normal, so a projector authored looking down its own negative Z lands flush against the wall. It spawns in world space with a null parent: parenting to a collider with non-uniform scale distorted decals in a way no per-axis counter-scale could fix once rotation mixed the axes. The cost, stated plainly in the source, is that decals no longer follow moving geometry.

After the pool hands back the instance, the service calls PooledHitDecal.Configure with the resolved lifetime and size. The component restarts its own timer and applies a uniform localScale, which is correct precisely because there is no parent chain to counter-correct.

The particle spawns at the same point with rotation aligned to the normal rather than against it, and gets a PooledParticleAutoDespawn added if the prefab does not already carry one. Finally, when a cue string survived the override fold, the service publishes a HitImpactAudioCueEvent on the Foundry event bus. VFX never creates an AudioSource.

IPrefabPoolService keys pools by prefab reference, so two surfaces sharing a decal prefab share one pool rather than fragmenting into two. WarmupAll walks the registry and warms each surface's decal to its InitialPoolSize and its particle to a quarter of that, with a floor of four, because particles are shorter-lived and fewer are in flight at once.

PooledHitDecal implements IPooledLifecycle and owns its own retirement. It counts down from spawn, fades alpha over the last twenty percent of its window through a cached MaterialPropertyBlock rather than an instance material, and then despawns itself through the pool service. The fallback path destroys the GameObject outright if no pool service is registered, so a misconfigured scene leaks nothing permanent.

The timer lives on the decal, so the service's hot path carries no list of in-flight decals to scan every frame.

When a resolved surface or its impact-class override declares a cue, HitDecalService publishes HitImpactAudioCueEvent carrying the cue id, the surface id, the impact class id, and the impact point and normal. Any audio package can subscribe; VFX depends on none of them.

That is the same decoupling rule the rest of Foundry uses. The package that knows what was hit publishes the fact; the package that knows how to make noise subscribes to it. Neither compiles against the other.