494 lines
31 KiB
Markdown
494 lines
31 KiB
Markdown
|
|
# Shield Panel: GPU Fracture Simulation Cut Map
|
|||
|
|
|
|||
|
|
Date: 2026-09-18
|
|||
|
|
|
|||
|
|
Status: Imagination pass, cut map. Nothing here has landed. Repo anchors are against
|
|||
|
|
`codex/item-provenance` HEAD `491811bd`. The six incoming sources are not in the repo
|
|||
|
|
yet; they are anchored as `files/<name>:<line>` against the operator's drop at
|
|||
|
|
`<scratch>/files/`.
|
|||
|
|
|
|||
|
|
Mechanism claims marked **(probe)** were run, not reasoned. The probe was a throwaway
|
|||
|
|
Unity 6000.3.24f1 project in scratch (`<scratch>/probe`), holding only the six files, a
|
|||
|
|
built-in port of the shader, and one editor script driven by
|
|||
|
|
`-batchmode -executeMethod`. Nothing was built in the Aetheria tree and no Unity session
|
|||
|
|
was opened against it; Hands was concurrently editing `Assets/Content`,
|
|||
|
|
`Packages/manifest.json` and the Addressables surfaces. Logs: `<scratch>/probe{,2..6}.log`.
|
|||
|
|
The probe project is scratch and will be removed with the session; §1 records what it
|
|||
|
|
proved so no one has to re-run it to trust the map.
|
|||
|
|
|
|||
|
|
## 0. Target
|
|||
|
|
|
|||
|
|
Operator, 2026-09-18: **wire it up to real hits.** The absorb capability in the
|
|||
|
|
`FieldShieldTest` scene drives the fracture panel; no standalone click-to-hit harness is
|
|||
|
|
built first.
|
|||
|
|
|
|||
|
|
Ends:
|
|||
|
|
|
|||
|
|
- A `ShieldPanel` exists in `FieldShieldTest`, materialises on load, and fractures when
|
|||
|
|
the absorb capability publishes an `AbsorbEvent`.
|
|||
|
|
- The event is the only input to the simulation. Presentation converts; it decides
|
|||
|
|
nothing about the rule, matching `Assets/Scripts/Gameplay/CapabilityPresenters.cs:8`
|
|||
|
|
and the fork-L contract in `Assets/Scripts/ServerShared/CapabilityEvents.cs:9-20`.
|
|||
|
|
- The sources compile and render on the built-in render pipeline. Aetheria has no URP:
|
|||
|
|
`ProjectSettings/GraphicsSettings.asset:41` is `m_CustomRenderPipeline: {fileID: 0}`
|
|||
|
|
and `Packages/manifest.json` carries no render-pipeline package.
|
|||
|
|
|
|||
|
|
Invariants:
|
|||
|
|
|
|||
|
|
- **One owner of the hit.** `ShieldPanel.Hit` is the only entry point into the
|
|||
|
|
simulation. The presenter is the only caller. Nothing else reaches the panel.
|
|||
|
|
- **One event, one hit.** An `AbsorbEvent` produces exactly one `Hit`, carrying the
|
|||
|
|
event's own world position and direction unmodified.
|
|||
|
|
- **Presentation owns only presentation.** Damage-type-to-pattern and magnitude-to-energy
|
|||
|
|
are presentation mappings authored on the presenter. The absorb capability's data (the
|
|||
|
|
damage-type mask) stays out of scope, as ruled 2026-09-17.
|
|||
|
|
- **No second render pipeline.** Nothing in this cut adds a package, a pipeline asset, or
|
|||
|
|
a URP include path.
|
|||
|
|
- **No Unity.Mathematics.** The incoming sources use `UnityEngine.Vector2/Vector3` only
|
|||
|
|
(verified: no `Unity.Mathematics` or `using static Unity` in any of the six). The
|
|||
|
|
presenter converts `CultMath.float3` with `CultMath.UnityBridge`, the way
|
|||
|
|
`Assets/Scripts/Gameplay/FieldDriver.cs:125` already does.
|
|||
|
|
|
|||
|
|
## 1. Probe record
|
|||
|
|
|
|||
|
|
All results from Unity 6000.3.24f1, Direct3D12, `srp=builtin`, batchmode with graphics.
|
|||
|
|
|
|||
|
|
1. **The shader ports to built-in with three substitutions.** Removing
|
|||
|
|
`"RenderPipeline"="UniversalPipeline"` from the SubShader tags, replacing the URP
|
|||
|
|
`Core.hlsl` include with `UnityCG.cginc`, and renaming the three
|
|||
|
|
`TransformWorldToHClip(` calls to `UnityWorldToClipPos(` is sufficient:
|
|||
|
|
`shader supported=True, messages=0` (probe3 had one warning, see §1.7). No other URP
|
|||
|
|
symbol is used — `_ScreenParams`, `noperspective`, `clip`, `saturate` and
|
|||
|
|
`StructuredBuffer` at `#pragma target 4.5` are all built-in surface. **(probe)**
|
|||
|
|
2. **Indirect drawing works on built-in.** `Graphics.RenderPrimitivesIndirect` with
|
|||
|
|
`RenderParams`, a `MaterialPropertyBlock` carrying `GraphicsBuffer`s, and an append
|
|||
|
|
buffer counter copied in by `GraphicsBuffer.CopyCount` rendered the panel:
|
|||
|
|
`argsFill vertsPerInstance=24 instanceCount=253`, 38036 of 65536 pixels lit. The cut
|
|||
|
|
does not have to change the drawing strategy. **(probe)**
|
|||
|
|
3. **`RenderParams` has no `shaderPass`.** Full property list in 6000.3.24f1:
|
|||
|
|
`layer renderingLayerMask rendererPriority instanceID entityId worldBounds camera
|
|||
|
|
motionVectorMode reflectionProbeUsage material matProps shadowCastingMode
|
|||
|
|
receiveShadows lightProbeUsage lightProbeProxyVolume overrideSceneCullingMask
|
|||
|
|
sceneCullingMask forceMeshLod meshLodSelectionBias`. `files/ShieldPanel.cs:410,415,420`
|
|||
|
|
do not compile. **(probe)**
|
|||
|
|
4. **A multi-pass material renders every pass from one call.** A two-pass probe shader
|
|||
|
|
(red triangle in pass 0, green in pass 1) drawn once with `Graphics.RenderPrimitives`
|
|||
|
|
produced `redPixels=40992 greenPixels=40983`. Pass selection is not available at this
|
|||
|
|
API, so the supplied "one args buffer per pass index" design cannot work as written.
|
|||
|
|
**(probe)**
|
|||
|
|
5. **One args buffer sized to the widest pass is equivalent.** Setting every args buffer
|
|||
|
|
to `MaxVerts * 2 * 6 = 96` vertices per instance and issuing a single
|
|||
|
|
`RenderPrimitivesIndirect` produced pixel-identical output to the three-call version:
|
|||
|
|
`singleCall=False litPixels=43929` vs `singleCall=True litPixels=43929`. Each pass
|
|||
|
|
already culls its own surplus vertices (`files/ShieldPanel.shader:238` fill,
|
|||
|
|
`:287` outline, `:347` conduit), and additive `Blend One One` with `ZWrite Off` makes
|
|||
|
|
pass order irrelevant. **(probe)**
|
|||
|
|
6. **`centroid` is a reserved word in the compute path.** `ShieldSim.compute` failed with
|
|||
|
|
`Error 18: syntax error: unexpected token 'centroid' at kernel KInit` — the
|
|||
|
|
`CellStatic.centroid` member at `files/ShieldCommon.hlsl:18`. Renaming it to `center`
|
|||
|
|
in the HLSL, compute and shader gives `compute supported=True, messages=0`. The
|
|||
|
|
fragment/vertex compiler tolerates it; the compute compiler does not. **(probe)**
|
|||
|
|
7. **One live shader warning survives the port:** `Warning 172: use of potentially
|
|||
|
|
uninitialized variable (BuildLine)`, Conduit vertex program. Warning only; the pass
|
|||
|
|
renders. Worth a look while touching `BuildLine`, not worth a cut of its own.
|
|||
|
|
8. **The supplied tuning never fractures anything.** Hex tiling, `panelRadius 5`,
|
|||
|
|
`cellSize 0.35`, 253 cells, a head-on Radial hit at the centre, 60 frames after:
|
|||
|
|
|
|||
|
|
| energy | broken | maxDamage | maxPeakTension | minTemper |
|
|||
|
|
| --- | --- | --- | --- | --- |
|
|||
|
|
| 3.5 (the supplied "strong" hit) | 0/253 | 0 | 0.058 | 0.547 |
|
|||
|
|
| 35 | 0/253 | 0.0012 | 0.579 | 0.505 |
|
|||
|
|
| 60 | 0/253 | 0.0097 | 0.743 | 0.487 |
|
|||
|
|
| 90 | 0/253 | 0 | 0.076 | 0.548 |
|
|||
|
|
| 120 | 0/253 | 0 | 0 | 0.55 |
|
|||
|
|
| 160 | 0/253 | 0 | 0.084 | 0.549 |
|
|||
|
|
| 220 | 0/253 | 0 | 0 | 0.55 |
|
|||
|
|
| 350 | 0/253 | 0 | 0 | 0.55 |
|
|||
|
|
| 3500 | 0/253 | 0 | 0 | 0.55 |
|
|||
|
|
|
|||
|
|
A break needs `u > temper + tensileStrength*toughness ≈ 1.45` **and** `damage >= 0.75`.
|
|||
|
|
Peak tension is non-monotonic in energy and collapses above ~60: the field saturates
|
|||
|
|
into the compression clamp and never swings back into tension. Causes named in §5
|
|||
|
|
(D9, D10). **(probe)** This is the reason Cut 4 exists and why it is the operator's
|
|||
|
|
first fork: wiring real hits to a simulation that cannot break is a pretty stress wave
|
|||
|
|
and nothing else.
|
|||
|
|
|
|||
|
|
## Cut 1. Land the sources, compiling, on built-in
|
|||
|
|
|
|||
|
|
- **Repo/branch:** Aetheria `codex/item-provenance` from `491811bd`. Depends on nothing.
|
|||
|
|
Touches no file Hands is holding (`Packages/manifest.json`, `Assets/Content`,
|
|||
|
|
`ServerShared` asset-path fields, `GameData/Aetheria.cc`, `ActionBarSlot.cs`,
|
|||
|
|
`UnityHelpers.cs`).
|
|||
|
|
- **First:** confirm Hands' Addressables cuts have landed or are on files disjoint from
|
|||
|
|
`Assets/Shaders/`. Nothing here goes near `Assets/Resources`, which is mid-move to
|
|||
|
|
`Assets/Content`.
|
|||
|
|
|
|||
|
|
**Location.** All six files go to `Assets/Shaders/Compute/ShieldField/`, matching the
|
|||
|
|
repo's own convention for compute-driven effects: `Assets/Shaders/Compute/Lightning/`
|
|||
|
|
holds `Lightning.compute`, `Lightning.shader`, `LightningVertex.cginc` and
|
|||
|
|
`LightningCompute.cs` together; `Slime/` does the same. Colocation is also load-bearing —
|
|||
|
|
`#include "ShieldCommon.hlsl"` resolves relative to the including file (probe). No import
|
|||
|
|
settings are needed: `.compute` and `.hlsl` import with no configurable state.
|
|||
|
|
|
|||
|
|
**Assembly.** No asmdef. The files land in `Assembly-CSharp` with everything else in
|
|||
|
|
`Assets/Shaders/Compute/*.cs` and `Assets/Scripts/Gameplay/`. The `ShieldField` namespace
|
|||
|
|
collides with nothing (`rg "class ShieldPanel\b|class Tilings\b|class Limits\b|enum
|
|||
|
|
TilingKind|class PolygonSoup|class VertexWelder|enum FracturePattern"` over
|
|||
|
|
`Assets/Scripts` and `Assets/Shaders` returns nothing). See Q7 for the testability cost.
|
|||
|
|
|
|||
|
|
**Deletes first:**
|
|||
|
|
|
|||
|
|
- `files/ShieldPanel.cs:450-487` — `ShieldPanelTester`. It is the standalone click harness
|
|||
|
|
the operator ruled against, and it cannot run anyway:
|
|||
|
|
`ProjectSettings/ProjectSettings.asset:797` is `activeInputHandler: 1` (new Input System
|
|||
|
|
only), so `Input.GetMouseButtonDown` and `Input.mousePosition` throw at runtime. Delete
|
|||
|
|
it rather than port it; the absorb path replaces it.
|
|||
|
|
- `files/ShieldPanel.cs:90` — `argsOutline`, `argsConduit` and their `MakeArgs` calls
|
|||
|
|
at `:172-173`, plus the `drawFill`/`drawOutline`/`drawConduits` bools at `:68-70` and
|
|||
|
|
their branches at `:408-422`. Replaced by one args buffer and one draw (probe §1.5).
|
|||
|
|
Per-pass toggles come back as a fork (Q6) if the operator wants them, and then as
|
|||
|
|
shader uniforms, not as draw calls.
|
|||
|
|
|
|||
|
|
**Per-file changes (against the supplied files):**
|
|||
|
|
|
|||
|
|
- `ShieldCommon.hlsl:18` — `float2 centroid;` → `float2 center;`. Every `.centroid` in
|
|||
|
|
`ShieldSim.compute` and `ShieldPanel.shader` follows. Required to compile (§1.6).
|
|||
|
|
- `ShieldCommon.hlsl:31` — add `float pad2;` after `pad1`, taking `CellStatic` to 16
|
|||
|
|
floats.
|
|||
|
|
- `TilingBuilder.cs:27` — add `public float pad2;` and initialise it at `:242`. Today the
|
|||
|
|
C# struct is 15 floats (60 bytes) while `Stride` at `:28` claims `4 * 16` (64), and
|
|||
|
|
`SetData` throws: *"One of C# data stride (60 bytes) and Buffer stride (64 bytes) should
|
|||
|
|
be multiple of other"* (probe). Padding to 16 keeps the 16-byte-aligned stride the
|
|||
|
|
comment intends; the alternative, `Stride = 4 * 15`, also works and is smaller. Either
|
|||
|
|
fixes it — do not fix only one side.
|
|||
|
|
- `TilingBuilder.cs:214` — rename the inner `dist` to `nbrDist` (and `:221`). CS0136: it
|
|||
|
|
shadows the `dist` declared at `:225` in the enclosing scope. The file does not compile
|
|||
|
|
as delivered (probe).
|
|||
|
|
- `ShieldPanel.shader:27` — drop `"RenderPipeline"="UniversalPipeline"`, add
|
|||
|
|
`"IgnoreProjector"="True"`.
|
|||
|
|
- `ShieldPanel.shader:33` — `#include "UnityCG.cginc"` in place of the URP `Core.hlsl`.
|
|||
|
|
- `ShieldPanel.shader:162,163,244` — `TransformWorldToHClip(` → `UnityWorldToClipPos(`.
|
|||
|
|
- `ShieldPanel.cs:171-173` — one `argsFill = MakeArgs((uint)(MaxV * 2 * 6));`.
|
|||
|
|
- `ShieldPanel.cs:369-371` — one `GraphicsBuffer.CopyCount(bVisible, argsFill, sizeof(uint));`.
|
|||
|
|
- `ShieldPanel.cs:408-422` — one `Graphics.RenderPrimitivesIndirect(rp,
|
|||
|
|
MeshTopology.Triangles, argsFill, 1, 0);`, no `rp.shaderPass`.
|
|||
|
|
- `ShieldPanel.cs:296-298` — hoist the `new uint[] { 0u, cap }` to a cached field. It
|
|||
|
|
allocates every frame today.
|
|||
|
|
- `ShieldPanel.cs:9` — drop `[ExecuteAlways]` (Q5). With it, `Update` runs the whole
|
|||
|
|
simulation and three GPU dispatch groups every editor frame in every open scene view,
|
|||
|
|
and `OnEnable` rebuilds the tiling on every domain reload.
|
|||
|
|
- Defect fixes D3-D8 from §5, each named in the commit.
|
|||
|
|
|
|||
|
|
**Authority map:**
|
|||
|
|
|
|||
|
|
- Owner: `ShieldPanel` owns the simulation and its GPU buffers. `TilingBuilder` owns
|
|||
|
|
adjacency, areas and the free-surface ghost weights. `Tilings` owns geometry generation.
|
|||
|
|
- Inputs: authored fields on the component; `Hit(worldPos, worldDir, energy, pattern,
|
|||
|
|
radius)` from outside.
|
|||
|
|
- Outputs: three indirect draws' worth of pixels, and GPU state readable for verification.
|
|||
|
|
- Derived state: `worldBounds`, `groups`, `echoSlot`, `simTime` are derived from the data
|
|||
|
|
and the frame clock; none is authored.
|
|||
|
|
- Forbidden writers: nothing outside `ShieldPanel` touches `bState`, `bUA/bUB`, `bV`,
|
|||
|
|
`bEcho`, `bFlow`, `bVisible`, `bBudget` or the args buffer. `ShieldPanelTester` is
|
|||
|
|
deleted rather than kept as a second hit source.
|
|||
|
|
- Shared paths: edit-mode and play-mode take the same `Update` body (once `ExecuteAlways`
|
|||
|
|
is settled); `Rebuild` is the only path that allocates, and always releases first.
|
|||
|
|
- Deletion line: `ShieldPanelTester`, the two surplus args buffers, the three draw bools,
|
|||
|
|
and the `rp.shaderPass` writes are gone before the presenter is written.
|
|||
|
|
|
|||
|
|
**Verification:**
|
|||
|
|
|
|||
|
|
- builds: Unity batchmode compile of the Aetheria project (`-quit -batchmode
|
|||
|
|
-projectPath . -logFile`), zero errors. `ShaderUtil.GetShaderMessages` on
|
|||
|
|
`ShieldPanel.shader` and `GetComputeShaderMessages` on `ShieldSim.compute` report zero
|
|||
|
|
errors (the §1.7 warning may remain).
|
|||
|
|
- test: none. The rule worth pinning is in Cut 2; there is nothing here a unit test would
|
|||
|
|
hold that the compiler does not.
|
|||
|
|
- negative: `rg "UniversalPipeline|render-pipelines\.universal|TransformWorldToHClip"
|
|||
|
|
Assets/Shaders/Compute/ShieldField` is empty. `rg "shaderPass" Assets` is empty
|
|||
|
|
(verified: no legitimate use of that identifier in the tree today).
|
|||
|
|
- operator: none yet. Cut 3 is the first thing to look at.
|
|||
|
|
|
|||
|
|
## Cut 2. The absorb presenter
|
|||
|
|
|
|||
|
|
- **Repo/branch:** same. Depends on Cut 1.
|
|||
|
|
- **Adds:** `Assets/Scripts/Gameplay/ShieldPanelPresenter.cs`, one component,
|
|||
|
|
`MonoBehaviour, IAbsorbPresenter`.
|
|||
|
|
- **Deletes:** nothing. `FieldDriver.Absorb` (`Assets/Scripts/Gameplay/FieldDriver.cs:158`)
|
|||
|
|
stays or goes by operator ruling Q2; the binder already supports both presenters
|
|||
|
|
subscribing to the same stream
|
|||
|
|
(`Assets/Scripts/Gameplay/CapabilityPresentationBinder.cs:32-36` iterates every
|
|||
|
|
`IAbsorbPresenter` in the children).
|
|||
|
|
|
|||
|
|
**Shape:**
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
public class ShieldPanelPresenter : MonoBehaviour, IAbsorbPresenter
|
|||
|
|
{
|
|||
|
|
public ShieldPanel Panel; // sibling object, not a child
|
|||
|
|
public float EnergyScale = 1f; // AbsorbEvent.Magnitude -> panel energy
|
|||
|
|
public float HitRadius = -1f; // -1 = the panel's own default
|
|||
|
|
public FracturePattern[] PatternByDamageType; // indexed by (int)DamageType, length 6
|
|||
|
|
|
|||
|
|
public void Absorb(AbsorbEvent e)
|
|||
|
|
{
|
|||
|
|
if (Panel == null) return;
|
|||
|
|
Panel.Hit(e.Position.ToUnity(), e.Direction.ToUnity(),
|
|||
|
|
e.Magnitude * EnergyScale, PatternFor(e.DamageType), HitRadius);
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
`AbsorbEvent.Position` is the world hit point and `Direction` is the incoming ray
|
|||
|
|
direction (`Assets/Scripts/UI/FieldTester.cs:76` publishes `hit.point` and
|
|||
|
|
`ray.direction`), which is exactly what `Hit` wants — `files/ShieldPanel.cs:257-282`
|
|||
|
|
transforms both into panel space itself. No projection, no normalisation, no
|
|||
|
|
reinterpretation on the presentation side: that is the "one event, one hit" invariant.
|
|||
|
|
|
|||
|
|
`PatternFor` reads the serialized table and falls back to `FracturePattern.Radial` when
|
|||
|
|
the array is short or unset, so an unauthored component still works. The mapping itself is
|
|||
|
|
Q3.
|
|||
|
|
|
|||
|
|
**Authority map:**
|
|||
|
|
|
|||
|
|
- Owner: `ShieldPanelPresenter` owns the event-to-hit conversion, and nothing else.
|
|||
|
|
- Inputs: one `AbsorbEvent`; three authored fields.
|
|||
|
|
- Outputs: one `ShieldPanel.Hit` call.
|
|||
|
|
- Derived state: none. The presenter holds no per-hit state, no queue, no timers — the
|
|||
|
|
panel already queues hits (`files/ShieldPanel.cs:82`).
|
|||
|
|
- Forbidden writers: the presenter never touches `CapabilityEvents`; the binder owns
|
|||
|
|
subscription. It never reads `FieldDriver`. Nothing writes `ShieldPanel` fields at
|
|||
|
|
runtime except its own inspector values.
|
|||
|
|
- Shared paths: the operator's click and any later real absorb capability reach the panel
|
|||
|
|
through the same `Absorb` method, because both go through `CapabilityEvents.Absorb`.
|
|||
|
|
- Deletion line: none; this cut is purely additive, and buys the only wiring the operator
|
|||
|
|
asked for.
|
|||
|
|
|
|||
|
|
**Verification:**
|
|||
|
|
|
|||
|
|
- builds: project compiles.
|
|||
|
|
- test: nothing in `Assets/Scripts/Tests` can reach `Assembly-CSharp` (`Tests.asmdef`
|
|||
|
|
references only `UnityEngine.TestRunner`, `UnityEditor.TestRunner` and
|
|||
|
|
`Aetheria.Shared.Unity`, and `autoReferenced: false`). So the rule is pinned by a
|
|||
|
|
batchmode probe instead, and the probe checks it at the layer where it would break:
|
|||
|
|
build a `CapabilityEvents`, a `CapabilityPresentationBinder`, the presenter and a real
|
|||
|
|
panel; publish one `AbsorbEvent` at a known off-centre position; step the sim; read
|
|||
|
|
`bState` back and assert the injected region is centred where the event said and that a
|
|||
|
|
second identical publish doubles it. A presenter with `Panel == null` publishes and does
|
|||
|
|
not throw. See Q7 for the alternative that buys NUnit coverage.
|
|||
|
|
- negative: `rg "ShieldPanel" Assets/Scripts --glob '!ShieldPanelPresenter.cs'` finds no
|
|||
|
|
second caller of `Hit`.
|
|||
|
|
|
|||
|
|
## Cut 3. The scene rig
|
|||
|
|
|
|||
|
|
- **Repo/branch:** same. Depends on Cuts 1-2.
|
|||
|
|
- **Touches:** `Assets/Scenes/FieldShieldTest.unity` only.
|
|||
|
|
|
|||
|
|
**Geometry.** The existing field is `Assets/Prefabs/cubesphere Variant.prefab`, a unit
|
|||
|
|
cubesphere scaled `(10, 10, 20)` at the origin, with the camera at `(0, 0, -50)` looking
|
|||
|
|
`+Z`. `ShieldPanel` builds a flat disc in local XY with its normal on `+Z`. So the panel
|
|||
|
|
becomes a **top-level scene object** at `(0, 0, -10)` with identity rotation and unit
|
|||
|
|
scale, `panelRadius = 10` — the near face of the field, same silhouette, undistorted. It
|
|||
|
|
must not be parented to the field: the field's non-uniform `(10,10,20)` scale would ride
|
|||
|
|
into `_PanelToWorld` and shear every shard.
|
|||
|
|
|
|||
|
|
Clicks already land on the field's `MeshCollider` and the absorb event carries that world
|
|||
|
|
point, whose X/Y is what the panel consumes. The panel therefore needs no collider of its
|
|||
|
|
own and no change to `ClickableCollider` or the click catcher.
|
|||
|
|
|
|||
|
|
**Wiring.** The presenter component goes on the **field** GameObject, next to
|
|||
|
|
`FieldDriver`, `ClickableCollider` and `CapabilityPresentationBinder`, because the binder
|
|||
|
|
finds presenters with `GetComponentsInChildren` on its own object
|
|||
|
|
(`CapabilityPresentationBinder.cs:32`). Its `Panel` field points at the separate panel
|
|||
|
|
object. One cross-reference, no scale contamination.
|
|||
|
|
|
|||
|
|
**How the scene is changed.** Hands cannot click, and hand-editing the YAML means
|
|||
|
|
inventing fileIDs next to a prefab instance with an override list — the exact shape that
|
|||
|
|
produced `1428ada3` ("Repair the Addressables map after a bad sed prefixed every line").
|
|||
|
|
So: a throwaway editor script under `Assets/Scripts/Editor/`, run once by
|
|||
|
|
`-batchmode -executeMethod`, that opens the scene, creates the panel object, adds and
|
|||
|
|
configures `ShieldPanel` (assigning the shader and compute assets by
|
|||
|
|
`AssetDatabase.LoadAssetAtPath`), adds the presenter to the field object, assigns the
|
|||
|
|
reference, and `EditorSceneManager.SaveScene`s. **The script is deleted in the same
|
|||
|
|
commit; the scene diff is the artifact.** Keeping it would mean a second authority over
|
|||
|
|
the rig that nobody would remember to re-run. Q4 offers the alternatives.
|
|||
|
|
|
|||
|
|
**Authority map:**
|
|||
|
|
|
|||
|
|
- Owner: the scene owns the rig. The editor script is a one-shot actuator with no
|
|||
|
|
standing authority and no life after the commit.
|
|||
|
|
- Inputs: the two prefab/asset GUIDs and the transform numbers above.
|
|||
|
|
- Outputs: one new GameObject, one new component on the field object, one reference.
|
|||
|
|
- Derived state: none.
|
|||
|
|
- Forbidden writers: nothing may create a `ShieldPanel` at runtime; the scene is the only
|
|||
|
|
source. `FieldTester` is not modified — it already publishes the absorb events, and
|
|||
|
|
giving it knowledge of the panel would re-split the authority fork L just merged.
|
|||
|
|
- Shared paths: the scene load path and the editor script write the same objects, because
|
|||
|
|
the script is what writes the scene.
|
|||
|
|
- Deletion line: the editor script, before the commit closes.
|
|||
|
|
|
|||
|
|
**Verification:**
|
|||
|
|
|
|||
|
|
- builds: project compiles; the scene opens with no missing-script warnings.
|
|||
|
|
- test: a batchmode headless open of `FieldShieldTest.unity` asserting that exactly one
|
|||
|
|
`ShieldPanel` exists, that its `sim` and `panelShader` are non-null, and that the field
|
|||
|
|
object's presenter resolves to it.
|
|||
|
|
- negative: `rg "ShieldPanelTester" Assets` is empty.
|
|||
|
|
- operator: enter play mode in `FieldShieldTest`; the panel materialises as a lattice
|
|||
|
|
filling the field silhouette; clicking the field produces a visible stress wave
|
|||
|
|
travelling out from the click and reflecting off the rim; the properties panel is
|
|||
|
|
unchanged. Whether anything shatters is Cut 4.
|
|||
|
|
|
|||
|
|
## Cut 4. Make a hit actually break the panel
|
|||
|
|
|
|||
|
|
- **Repo/branch:** same. Depends on Cut 3 and on ruling Q1.
|
|||
|
|
- **Blocked:** this cut is a tuning and mechanism pass, not a wiring pass. §1.8 shows no
|
|||
|
|
energy fractures the panel at the supplied defaults. Do not tune by eye first; the two
|
|||
|
|
mechanism defects below bound what tuning can reach.
|
|||
|
|
|
|||
|
|
**Per-file changes:**
|
|||
|
|
|
|||
|
|
- `ShieldSim.compute:226-232` — `u` is clamped to `±_StressClamp` while `v` is not. A hard
|
|||
|
|
hit drives `v` far past what the clamp permits, `u` pins at `-_StressClamp`, and the
|
|||
|
|
field never swings back into tension: that is the collapse above energy 60 in §1.8, and
|
|||
|
|
why 3500 behaves like 120. Clamp `v` as well, or normalise the injection so energy maps
|
|||
|
|
to a bounded velocity.
|
|||
|
|
- `ShieldPanel.cs:301` and `:359` — `_Dt` is set to `fixedSubstepDt` before the injection
|
|||
|
|
loop and not restored until after `KFracture` has been dispatched, so `KFracture`
|
|||
|
|
integrates damage and temper erosion with a substep `dt` while running **once per
|
|||
|
|
frame**. Damage accumulates roughly six times slower than the wave it is reading
|
|||
|
|
(`substeps = 6`). Either dispatch `KFracture` inside the substep loop, or hand it the
|
|||
|
|
frame `dt`. The first is physically honest and costs five more dispatches per frame; the
|
|||
|
|
second is one line. Pick one and say which in the commit — this is the "which clock owns
|
|||
|
|
fracture" question, not a constant.
|
|||
|
|
- `ShieldPanel.cs:34,53,56` and the presenter's `EnergyScale` — the tuning itself, once
|
|||
|
|
the two above are settled.
|
|||
|
|
|
|||
|
|
**Verification:**
|
|||
|
|
|
|||
|
|
- test: a batchmode probe that sweeps energy across the authored range, reads `bState`
|
|||
|
|
back, and asserts that the weak energy leaves `broken == 0` while the strong energy
|
|||
|
|
breaks a bounded, non-zero fraction of cells — the same readback shape as §1.8, which is
|
|||
|
|
cheap and already written once.
|
|||
|
|
- negative: no energy in the authored range leaves `maxPeakTension == 0` with
|
|||
|
|
`minTemper == temperInit`, the saturation signature.
|
|||
|
|
- operator: strong clicks dice the panel; repeated weak clicks eventually break through
|
|||
|
|
(the temper mechanism at `ShieldSim.compute:286-298` is the whole point of the design and
|
|||
|
|
is untested until a break is reachable).
|
|||
|
|
|
|||
|
|
## 5. Defects in the supplied code
|
|||
|
|
|
|||
|
|
Confirmed by compiling and running them, not by reading. D1-D4 are fatal; the cut does not
|
|||
|
|
exist without them.
|
|||
|
|
|
|||
|
|
| # | Where | Finding |
|
|||
|
|
| --- | --- | --- |
|
|||
|
|
| D1 | `files/TilingBuilder.cs:214` | CS0136: `dist` shadows the `dist` at `:225`. The file does not compile. **(probe)** |
|
|||
|
|
| D2 | `files/ShieldPanel.cs:410,415,420` | `RenderParams.shaderPass` does not exist in 6000.3.24f1. **(probe)** |
|
|||
|
|
| D3 | `files/TilingBuilder.cs:28` vs `:12-27` | `Stride = 4 * 16` but the struct is 15 floats; `SetData` throws on the stride mismatch. **(probe)** |
|
|||
|
|
| D4 | `files/ShieldCommon.hlsl:18` | `centroid` is reserved in the compute compiler; `ShieldSim.compute` does not compile. **(probe)** |
|
|||
|
|
| D5 | `files/ShieldPanel.cs:411-421` + probe §1.4 | Pass selection does not exist at this API, so the three per-pass args buffers cannot work as designed, independent of D2. |
|
|||
|
|
| D6 | `files/ShieldSim.compute:38` | Comment says `_BreakBudget` is a "single element"; the C# allocates two (`ShieldPanel.cs:162`) and `:304` reads index 1. **Not a bug — a lying comment.** The earlier reading of this as an overrun is refuted. |
|
|||
|
|
| D7 | `files/Tilings.cs:302-333` | `VoronoiCells` is O(n² log n): every site scans every other site and sorts the whole list, then `Voronoi` runs it `lloydPasses + 1` times (4 for `TilingKind.Voronoi`). Confirmed by reading; not a blocker for the Hex/Penrose default, a real wait at a few thousand sites. Use a partial selection (`nth_element`-style) or reuse the grid `ChaosGame` already builds at `:212`. |
|
|||
|
|
| D8 | `files/Tilings.cs:286-288` | `Vector2.zero` is both the "invalid cell" sentinel and a legal centroid, so a cell centred on the origin is silently refused relaxation. Use a nullable or a parallel validity flag. `idx` at `:292,297` is dead. |
|
|||
|
|
| D9 | `files/ShieldSim.compute:226-232` | `u` is clamped, `v` is not; hard hits pin the field in compression and no tension ever reflects. The measured collapse in §1.8. **(probe)** |
|
|||
|
|
| D10 | `files/ShieldPanel.cs:301,356,359` | `KFracture` runs once per frame but integrates with the substep `dt`, so damage and temper erosion accrue ~6× slow. |
|
|||
|
|
| D11 | `files/ShieldSim.compute:326-330` | `_V[e.nbr] +=` from many threads is a non-atomic read-modify-write; the cascade is nondeterministic run to run. Acceptable for an effect, worth knowing before anyone tries to write a test that pins an exact shard count. |
|
|||
|
|
| D12 | `files/ShieldPanel.cs:296-298` | A two-element `uint[]` is allocated every frame for the break budget. Cache it. |
|
|||
|
|
| D13 | `files/ShieldPanel.cs:9` | `[ExecuteAlways]` runs the full simulation, all dispatches and all draws every editor frame, and rebuilds the tiling on every domain reload. See Q5. |
|
|||
|
|
| D14 | `files/ShieldPanel.cs:426-440` | `ReleaseAll` does not clear `pending`, so hits queued before a rebuild are injected into the new tiling. Harmless today; wrong in principle. |
|
|||
|
|
| D15 | `files/ShieldPanel.shader` Conduit pass | `Warning 172: use of potentially uninitialized variable (BuildLine)`. Warning only. **(probe)** |
|
|||
|
|
| D16 | `files/Tilings.cs:91-116` | The TriHex interstitial triangles are placed by a separate polar construction rather than from the hex corners they should share, so welding is not guaranteed and the dual graph can come out with spurious free surfaces. Untested; `Hex` and `PenroseP3` are the safe defaults until someone looks. |
|
|||
|
|
|
|||
|
|
Buffer lifetime, `SetCounterValue` and `CopyCount` were checked specifically and are
|
|||
|
|
**correct**: `bVisible` is created `Append | Structured`
|
|||
|
|
(`files/ShieldPanel.cs:164`), reset at `:366` before the dispatch that appends, copied at
|
|||
|
|
`:369` into offset `sizeof(uint)` — which is `instanceCount` in
|
|||
|
|
`GraphicsBuffer.IndirectDrawArgs` — and every buffer is released by `ReleaseAll` on both
|
|||
|
|
`OnDisable` and the head of `Rebuild`. The probe's readback of
|
|||
|
|
`argsFill instanceCount=253` against `cells=253` confirms the counter path end to end.
|
|||
|
|
**(probe)**
|
|||
|
|
|
|||
|
|
Per-frame cost, measured shape: 253 cells → 1 inject dispatch per queued hit, 12 dispatches
|
|||
|
|
for six wave substeps plus their echoes, 1 fracture, 1 update, 1 `CopyCount`, 1 buffer
|
|||
|
|
upload, 1 indirect draw. At the scene's panel radius of 10 with `cellSize 0.35` expect
|
|||
|
|
roughly four times the cells and the same dispatch count. Nothing here is close to a
|
|||
|
|
budget problem in a test scene; the only per-frame CPU waste is D12.
|
|||
|
|
|
|||
|
|
## 6. Subtraction ledger
|
|||
|
|
|
|||
|
|
| Cut | Removed | Added | Deps/targets |
|
|||
|
|
| --- | --- | --- | --- |
|
|||
|
|
| 1 | `ShieldPanelTester` (~38 lines), 2 args buffers, 3 draw bools, 2 draw calls, `ExecuteAlways` | 6 files (~5.4k lines) | none added; no package, no pipeline, no asmdef |
|
|||
|
|
| 2 | — | 1 file (~35 lines) | none |
|
|||
|
|
| 3 | the one-shot editor script, in the same commit | 1 scene object, 1 component instance | none |
|
|||
|
|
| 4 | — | ~5 lines changed | none |
|
|||
|
|
|
|||
|
|
Net: strongly additive, and it should be. The capability bought is a simulation that does
|
|||
|
|
not exist in the tree in any form; nothing currently in the repo can be deleted in exchange
|
|||
|
|
for it, and the only existing machine it might replace — `FieldDriver`'s absorb visual — is
|
|||
|
|
the operator's call in Q2, not a subtraction this map may assume.
|
|||
|
|
|
|||
|
|
## 7. Operator questions
|
|||
|
|
|
|||
|
|
Most blocking first.
|
|||
|
|
|
|||
|
|
**Q1 — Does the first landing have to fracture?** §1.8 says no energy breaks a cell at the
|
|||
|
|
supplied defaults, and two mechanism defects (D9, D10) bound what tuning alone can reach.
|
|||
|
|
A: land Cuts 1-3 now, ship a visibly-materialising panel with a real stress wave and no
|
|||
|
|
fracture, and take Cut 4 as its own pass with its own probe. B: hold the whole thing until
|
|||
|
|
Cut 4 lands too, so the first thing seen is the effect as designed. **Recommended: A.**
|
|||
|
|
Wiring is the thing ruled on, it is verifiable on its own, and separating it means the
|
|||
|
|
tuning pass gets judged against a rig that already works instead of against itself. The
|
|||
|
|
cost is one operator look that ends in "nothing broke," which is the honest state.
|
|||
|
|
|
|||
|
|
**Q2 — Does the panel replace the field shield's absorb visual or sit alongside it?**
|
|||
|
|
`FieldDriver.Absorb` (`FieldDriver.cs:158`) feeds the existing ellipsoid ripple, and the
|
|||
|
|
binder subscribes every `IAbsorbPresenter` it finds, so both can run from the same event
|
|||
|
|
with no code change. A: both, for comparison. B: panel only — remove `IAbsorbPresenter`
|
|||
|
|
from `FieldDriver` and let its hit buffer machinery (`:76,105-132,204-217`) go with it.
|
|||
|
|
**Recommended: A for the first landing, then B as a deliberate deletion once the panel has
|
|||
|
|
been looked at.** Keeping both permanently would be two absorb visuals with no rule about
|
|||
|
|
which owns the read; that is exactly the split this map should not create.
|
|||
|
|
|
|||
|
|
**Q3 — Which fracture pattern does each damage type get, and where is it authored?** Six
|
|||
|
|
of each, no natural ordering. Proposed table: Kinetic→Radial, Optical→Lance,
|
|||
|
|
Electric→Star, Thermal→Crystal, Corrosive→Fizzle, Ionizing→Spiral. Authoring: A: a
|
|||
|
|
serialized `FracturePattern[]` on the presenter, indexed by `(int)DamageType`. B: a switch
|
|||
|
|
in code. C: gameplay settings or item data. **Recommended: A.** It is presentation choice,
|
|||
|
|
it belongs with the presentation, and the operator can retune it without a compile. C is
|
|||
|
|
wrong today: the absorb capability owns no data yet, and `CapabilityEvents.cs:17-20`
|
|||
|
|
explicitly parks that.
|
|||
|
|
|
|||
|
|
**Q4 — How is the scene edited?** A: a one-shot editor script run in batchmode and deleted
|
|||
|
|
in the same commit. B: hand-edited scene YAML. C: the operator clicks it together in the
|
|||
|
|
editor. **Recommended: A.** B is the failure mode that produced `1428ada3`; C costs the
|
|||
|
|
operator's hands for something deterministic. If the operator would rather keep the script
|
|||
|
|
as a menu item, say so — that turns it into a standing second authority over the rig and
|
|||
|
|
should be a deliberate choice, not a leftover.
|
|||
|
|
|
|||
|
|
**Q5 — `[ExecuteAlways]`?** A: drop it; the panel is inert until play mode. B: keep it, so
|
|||
|
|
the lattice is visible while authoring the scene. **Recommended: A**, with `Rebuild` kept
|
|||
|
|
on the context menu so a deliberate editor preview is still one click. Keeping it runs a
|
|||
|
|
full GPU simulation in every open scene view forever, for authoring convenience that a
|
|||
|
|
context menu already provides.
|
|||
|
|
|
|||
|
|
**Q6 — Per-pass draw toggles?** The supplied `drawFill`/`drawOutline`/`drawConduits` bools
|
|||
|
|
die with the single-call draw (probe §1.5). A: gone. B: back as shader uniforms that zero
|
|||
|
|
each pass's alpha. **Recommended: A**, until someone wants them; B is two minutes' work
|
|||
|
|
the day that happens, and the toggles have no consumer today.
|
|||
|
|
|
|||
|
|
**Q7 — Buy NUnit coverage with an asmdef?** `Tests.asmdef` cannot reference
|
|||
|
|
`Assembly-CSharp`, so no unit test can see the presenter as mapped. A: no asmdef; pin the
|
|||
|
|
rule with the batchmode probe in Cut 2, which checks the whole path from published event
|
|||
|
|
to GPU state. B: add `Aetheria.ShieldField.asmdef` over the six files plus the presenter,
|
|||
|
|
referencing `Aetheria.Shared.Unity`, and let `Tests` reference it. **Recommended: A.** B
|
|||
|
|
buys a test of the arithmetic in a one-line method while adding a compile boundary and a
|
|||
|
|
reference edge to a project that has two test files total; the probe checks the thing that
|
|||
|
|
would actually break, at the layer it would break.
|
|||
|
|
|
|||
|
|
**Q8 — Which tiling is the default?** The component ships `PenroseP3` with
|
|||
|
|
`mergeRhombs`. `Hex` is what the probe exercised and the only one whose adjacency was
|
|||
|
|
verified. `Voronoi` costs D7 at init and `TriHex` carries D16. A: Penrose, as authored. B:
|
|||
|
|
Hex for the first landing, Penrose once the rig is looked at. **Recommended: B**, then move
|
|||
|
|
to whatever looks right — this is a look-at-it decision, not a correctness one.
|