Skip to content

Runtime decals in the client: modular objects, child parts, placement queries - #150

Draft
JuhDuh26 wants to merge 19 commits into
carbonengine:mainfrom
JuhDuh26:modular-hull-runtime-decals
Draft

JuhDuh26 wants to merge 19 commits into
carbonengine:mainfrom
JuhDuh26:modular-hull-runtime-decals

Conversation

@JuhDuh26

@JuhDuh26 JuhDuh26 commented Nov 11, 2026 •

Copy link
Copy Markdown

What

Runtime EveSpaceObjectDecals (decals created from Python, with no baked index buffers) now render in the game client, on modular objects and on everything an object draws, not only its own mesh. EVE Frontier uses them for collision scratches on Creation hulls and on level geometry.

  • Modular objects: decals render on meshless EveStation2s built by CreateModularObject (Creation hulls). GetDecalPrimitiveCounts() no longer crashes on a decal with no mesh behind it.
  • Client builds: a new dynamicIndexBuffers decal flag lets a runtime decal build its own geometry outside content mode (buildDecalBuffers stays off in the client).
  • Triangle cache: each mesh's triangles are cached in a spatial grid on first use, so a decal build costs ~1 ms instead of a full scan. The first decal on a mesh does a one-off readback and a background build (about a second). Builds run as tasks in one task group, drained by Tr2Renderer::Shutdown: a frame starts at most one readback (tens of ms on a large mesh), and up to a quarter of the hardware threads (at least two) build at once; a failed readback backs off (2 s, doubling to 60 s); memory is reported as Trinity/decalTriangleCacheBytes, and a cache nothing has used for 60 s is freed (and rebuilt on next use).
  • All drawn geometry: runtime decals project onto the object's own mesh plus its children's parts, e.g. EveChildInstancedMeshes level geometry whose own mesh is a placeholder. Baked decals are unchanged. Part targets come from a broad phase that only reruns when the parts list or the decal volume changes. Skinned or morphed parts are left out, since their decal would be built on rest-pose triangles.
  • No smearing: runtime decals skip faces more than ~66° off their projection axis.
  • No z-fighting on parts: part decals use the LOD the part is actually drawn at, and are pulled towards the eye by enough to cover the part chain's float rounding (screen positions unchanged).
  • Cheap animation: a new growScale decal attribute (per axis, 0..1) shrinks the drawn volume without rebuilding the geometry. A position/rotation/scaling change that keeps the volume inside the one the geometry was built for doesn't rebuild either.
  • Queries for placement: EveSpaceObject2.GetNearestHullEdge(position, radius) and GetNearestSurfacePoint(position, radius) return (found, (position, normal)) in object space, over own mesh and parts. QueryNearestHullEdge and QueryNearestSurfacePoint return (status, (position, normal)), status 0 found, 1 none in reach, 2 pending (a part's cache is still building). The game snaps scratches to real geometry with them.

Commits

  • 10de9f62d Render runtime decals on modular objects
  • a7a5d17c5 Let runtime decals build their geometry in the client
  • 5a59f6a67 Cache mesh triangles for runtime decal builds
  • cf4f76f33 Find the nearest hull edge for runtime decals
  • b4c4c398d Keep runtime decals off faces they would smear across
  • 986605e65 Put runtime decals on everything an object draws
  • 006525a70 Draw part decals at their part's LOD, pulled towards the eye
  • c808d5d16 Size the part decal depth pull to the part's rounding
  • d1876b362 Find the nearest surface point for runtime decals
  • ba8a63b06 Run decal cache builds as capped tasks, drained at shutdown
  • b37386d2f Back off after a failed decal cache readback
  • f251cb1e0 Broad-phase decal part targets once per parts change
  • 30db88533 Report decal triangle cache memory in the statistics
  • da60928de Add decal growScale: animate the drawn volume without rebuilds
  • bfc34dba4 Tell a building geometry cache from nothing in reach
  • 7c7560ac6 Free decal triangle caches nothing has used for a minute
  • 5ded55e42 Keep a runtime decal's geometry while its volume stays inside
  • 9e13a6d57 Limit decal cache readbacks to one per frame, scale builds to cores
  • a9142e0e9 Keep runtime decals and placement queries off animated parts

Testing

Tested in Graphite and in a local EVE Frontier client (trinitydev build) with the game-side collision scratches: decals render on Creation hulls and on instanced level geometry, without flicker up close.

For the review fixes, in Graphite (trinitydev) on a modular Creation hull:

  • QueryNearestSurfacePoint/QueryNearestHullEdge report pending (2) on the first call while the hull's cache builds, found (0) once it is ready, and none (1) for a point 500 m off; GetNearestHullEdge still returns (True, ...).

  • Trinity/decalTriangleCacheBytes reads 620,740 for that hull's cache.

  • Edge scratches build geometry through the new part broad phase (217/149/107/80/43/32 triangles per LOD).

  • growScale = (1, 0.3, 1) leaves those counts unchanged (no rebuild) and draws the scratch at 30% of its length.

  • Idle release: the hull's cache read 620,756 bytes; after more than 60 s with no decal build or query against the hull it read 0. The next query reported pending (2) and then found (0), the statistic was back at 620,756, and two new scratches built 110 and 108 triangles from the rebuilt cache.

  • Volume inside the built one: shrinking a scratch's scaling to 60% kept its counts (217/149/107/80/43/32) with no rebuild; growing it to 150% dropped the geometry and rebuilt it the next frame (394/286/189/137/82/60).

  • One readback per frame: two hull meshes never seen before, asked about in the same frame, came back found one and two frames later respectively. The build cap is 8 on a 32-thread machine.

  • Animated-part filter: the Creation root hull (mod_data_root_01) and the level wall piece (kb_b_23v01) are static and still take scratches and answer queries.

The depth pull was sized with a float32 emulation of both transform chains: for an instance 38 km from its object origin seen from 7 m, the decal could sit 2.5 mm behind its surface; the pull covers that with a 3.5× margin.

Not doing / follow-ups

  • Reusing the ray-caster BVH instead of the decal triangle cache. That BVH is a separate asset, loaded asynchronously, that answers ray casts only. The decal build and the nearest-edge and nearest-surface searches need box and nearest-point queries, so reusing it means adding both to it and keeping the two loaded together; it would save memory only on meshes that also use the ray caster. A follow-up if the memory matters, now that idle caches are freed after a minute.
  • Exact depth for part decals instead of the sized pull towards the eye. Drawing them through InstancedDecalVS with each part's instance record would need an SOIA_ENABLED copy of the decal effect sharing its parameters, a per-part instance buffer, and the decal and hull shaders compiling pos · instance · world to identical floating point, which a test in Graphite can't establish. The pull keeps every pixel in place; a float32 emulation of the worst case (an instance 38 km from its origin, seen from 7 m) shows it covers the rounding 3.5 times over.
  • Decals on animated parts: skinned and morphed parts are now left out rather than decalled wrongly. Supporting them would mean skinning the decal with the part's bone palette.

🤖 Generated with Claude Code

JuhDuh26 and others added 15 commits November 11, 2026 11:09
A runtime EveSpaceObjectDecal (no static index buffers) builds its index
buffer by testing the parent mesh's triangles against the decal volume.
A modular object (EveStation2 from CreateModularObject + AddHull) has no
mesh of its own, so PushChildrenAndDecalRenderables skipped its decals
and nothing rendered.

When the parent has no mesh, gather the part geometries with
CollectOwnedGeometry and project each decal onto every part whose
bounds its volume touches. Each part gets its own index buffer, built
on the CPU with the decal volume moved into part space, and its own
per-object data (part world transform and part-space decal matrices).
The buffers are owned by the decal rather than cached on the shared
mesh data, since a hull geometry is shared between parts and runtime
decals come and go. They are rebuilt when the decal or a part moves. A
part's LOD follows its share of the object's screen size, as the
instanced mesh manager does. Unlike the single mesh path this is not
gated on buildDecalBuffers: modular objects have no precomputed decal
buffers, so building them is the only way to show the decal.

The triangle gather moves out of CreateDecalIndexBuffers into
BuildDecalGeometry and the batch setup into CommitBatch, shared by both
paths.

GetDecalPrimitiveCounts dereferenced m_baseGeometryResource when the
decal had no geometry, which access-violated for a decal on a meshless
model or with no parent. It now returns an empty list there, and for a
modular parent returns per-LOD counts summed over the parts.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A decal without static index buffers only builds its geometry when the
buildDecalBuffers setting is on, and the client enables it only in
content mode. Runtime decals on ordinary meshes (collision scratches on
level geometry) therefore never showed in the game.

Add a persisted dynamicIndexBuffers attribute. A decal with it set
builds its geometry whatever buildDecalBuffers says, and owns the
buffer instead of adding it to the mesh's shared decal cache, which
only grows and would collect one entry per scratch. Decals without the
attribute, including SOF decals that miss their baked buffers, behave
as before.

BuildDecalGeometry now skips the buffer readback when the decal volume
is outside the mesh bounds.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A runtime decal read every LOD of its mesh back from the GPU and tested
every triangle, about 120 ms per decal on a 3.66 M triangle level mesh.

The first runtime build against a mesh now copies its buffers back once
(main thread) and hands them to a worker thread that converts them and
buckets the triangles of each LOD into a hierarchical loose grid: each
triangle is stored once, in the cell of its centre on the finest level
whose cells fit it, with the index list reordered by cell. Later builds
only test the triangles in the cells around the decal box. Until the
worker finishes, the build returns nothing and the decal tries again on
a later frame.

The cache (DecalTriangleCache) hangs off TriGeometryResMeshData, so it
is freed with the mesh data on release, re-initialization and reload,
and is rebuilt if the mesh's LOD set changes. The worker owns its
copies, so releasing the mesh mid-build is safe.

Both runtime paths use it: decals with dynamicIndexBuffers and decals on
modular objects (which no longer need the per-frame DecalMeshCacheMap).
Decals built through buildDecalBuffers keep the old full scan and the
shared mesh cache.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
EveSpaceObject2.GetNearestHullEdge(position, radius) returns the point on an
edge of the object's geometry (its mesh, or a modular object's parts) nearest
to an object-space point, with the normal a decal there should project along
to wrap over the edge. An edge is a fold sharper than 30 degrees between two
triangles, matched by vertex position so split vertices join up, or an open
edge. The search runs on the per-mesh DecalTriangleCache, whose cell walk is
now shared with the decal query. Not found while a mesh's cache is building.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A runtime decal now leaves out triangles more than ~66 degrees off its
projection axis (either winding): its texture stretched into long streaks
along faces nearly parallel to the axis. A decal on an edge sits 45 degrees
to each face, so it still wraps the edge. Baked decals are unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Level geometry has a placeholder mesh of its own and draws through an
EveChildInstancedMeshes child, so its runtime decals were projected onto the
placeholder and found nothing. A runtime decal (dynamicIndexBuffers) on an
object with both now goes onto its mesh and its children's parts. Baked
decals, and those built by buildDecalBuffers, stay on the object's own mesh.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Part decals picked their LOD from the object's screen size scaled by the
part's size, so near a threshold a decal could sit on another LOD's triangles
than the part it marks, and flicker as the camera moved. They now pick it as
the part is drawn: the object's own mesh at the object's screen size,
instanced parts from the instance's sphere as EveChildInstancedMeshes sizes
it and EveInstancedMeshManager::GetMeshLod picks it.

A part decal's world matrix is composed on the CPU while the part is drawn
through the instanced path, so their depths differ by rounding and, with no
depth write or bias in the decal pass, can z-fight. Part decals are now scaled
by 1 - 4e-4 about the eye: no pixel moves, and the depth comes that fraction
of the distance closer. Decals on a single mesh are unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Level geometry instances sit tens of km from their object's origin, so the
hull's two-step instanced transform and the decal's composed matrix round
apart by millimetres whatever the camera distance: a fixed 0.04% pull left
the decal behind its surface up close. The pull now covers two float steps
at the largest coordinate in the part's transform chain, from the part's
nearest point to the eye (no nearer than 2 m), between 0.04% and 0.5%. Still
a scale about the eye, so no pixel moves.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
EveSpaceObject2.GetNearestSurfacePoint(position, radius) returns the point on
the object's own geometry nearest to an object-space point and that
triangle's normal, turned towards the point: where to put a decal, and the
true surface normal to project it along. It searches the same per-mesh
DecalTriangleCache as GetNearestHullEdge, which now shares the part walk.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Each cache build ran on its own detached std::thread: unbounded when many
meshes are first hit at once, and nothing joined them at exit. Builds now
run in one shared task group, at most two at a time (a mesh asked for beyond
that retries on a later frame, before any readback). Tr2Renderer::Shutdown
calls DecalTriangleCache::Shutdown, which stops new builds, cancels queued
ones and waits for the running ones; a cancelled build never marks its cache
ready.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
When reading a LOD back from the GPU failed, Get remembered nothing, so every
later call (every frame, for every decal on the mesh) paid the readback again,
tens of ms on a large mesh. The failure is now stored on the mesh as a failed
cache with a retry time: 2 s after the first failure, doubling up to 60 s.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Every frame, GetModularRenderables matched each part against every part
target with find_if (quadratic on the 55-mesh instanced level object) and
kept a target, with its part-space matrices, for every part, overlapping or
not. The parts list is now hashed each frame; only when the hash or the
decal volume changes does a broad phase run: the decal box against each
part's bounds in object space, keeping just the parts it touches and the
geometry already built for those that are unchanged. Unchanged frames only
look after the targets that exist.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The CPU triangle caches (about 30 bytes per triangle, so ~100 MB for a
3.7M-triangle mesh) were invisible to memory statistics. Each cache now adds
its size to the new Trinity/decalTriangleCacheBytes statistic (CST_MEMORY)
when Get first hands it out ready, and takes it off again when it is
destroyed with its geometry.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A change to position, rotation or scaling rebuilds a runtime decal's
geometry (and its part targets), so a curve animating scaling, such as a
scratch growing over its first 0.2 s, rebuilt it every frame. The new
growScale attribute (per axis, 0..1, default 1) shrinks only the volume the
decal is drawn in: its geometry stays built for the full scaling, the shader
gets the drawn matrices, and the decal texture's bordered sampler shows
nothing outside them. Changing growScale only recomputes those matrices;
each axis is held at 1e-4 or more so a grow from 0 stays invertible.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
GetNearestHullEdge and GetNearestSurfacePoint answered "not found" both when
nothing lies within the radius and when a part in reach was still building
its triangle cache (or held back by the build cap or a readback backoff), so
callers could not tell "give up" from "ask again". QueryNearestHullEdge and
QueryNearestSurfacePoint return (status, (position, normal)) with status 0
found, 1 none in reach (every part in reach searched), 2 pending. The Get
variants keep their (found, (position, normal)) results on top of them.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@JuhDuh26 JuhDuh26 changed the title Render runtime decals on modular objects Runtime decals in the client: modular objects, child parts, placement queries Nov 12, 2026
JuhDuh26 and others added 4 commits November 12, 2026 14:24
A mesh's triangle cache lived as long as the mesh: ~30 bytes per triangle,
~109 MB for a 3.66 M-triangle level piece, kept after the ship had left it.
Get (behind every decal build and every GetNearest*/QueryNearest* call) now
stamps the cache's last use. Once a second, from Tr2Renderer::EndFrame,
ReleaseIdle frees the triangles of every ready cache unused for 60 s, takes
its bytes off Trinity/decalTriangleCacheBytes and marks it released, so the
next Get rebuilds it.

A minute covers the gaps of a collision burst (a grind calls Get every metre,
a ship bumping around a piece returns within seconds), so those don't pay a
rebuild (a readback of tens of ms plus about a second of build).

The caches built are tracked in a small main-thread list of weak pointers, so
a cache released with its mesh just drops out and no mesh is reached through
it. A cache still building is never touched (its task owns it until ready),
and a failed readback, which holds no triangles, keeps its backoff.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Any change to a runtime decal's position, rotation or scaling threw its
geometry and part targets away and rebuilt them. Now, when the new volume
lies inside the one the geometry was built for (all eight corners within
it), the geometry and targets are kept and only the drawn matrices change:
every triangle the new volume touches is already in the built geometry, and
the decal texture's bordered sampler shows nothing outside the drawn volume.
A volume that leaves the built one rebuilds as before, and every rebuild
records the volume it was built from. Baked decals are unchanged; growScale
remains the way to animate growth without rebuilds.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The real cost of a first decal on a mesh is the main-thread GPU readback
(tens of ms on a large mesh), not the background build, yet nothing bounded
how many readbacks one frame could start; the build cap of two only
indirectly limited them. Get now starts at most one readback per frame (the
counter resets in DecalTriangleCache::EndFrame, which Tr2Renderer::EndFrame
calls and which also runs the idle release), so first hits on several new
meshes spread over frames. With that bound, the background build cap scales
with the machine: a quarter of the hardware threads, at least two (eight on
a 32-thread machine).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Part decals are built from a part's rest-pose triangles and drawn with an
identity parent bone, and the nearest-edge and nearest-surface queries read
the same rest-pose positions. On a skinned or morphed part (an EveChildMesh
can be either) the decal would stay behind as the part moved, and a query
would answer with where the part is not. Such parts are now left out of the
decal broad phase and of the queries (DecalTriangleCache::IsDeformed: any
area of the mesh skinned or morphed). Creation hull parts and instanced
level geometry are static and unaffected.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant