Files
Neutron/docs/gameplay/gadget-blending.md
T

84 lines
5.1 KiB
Markdown

# Gadget material opacity and blending
Implemented 2026-10-27. Scope: Vulkan support needed by the recovered shrink-ray
effect. This is a renderer capability, not a claim of complete original material
or fixed-function rendering fidelity.
## Recovered facts
[Shrink-ray investigation](shrink-ray.md) records the underlying REA evidence.
Original EXE SHA256:
`f5281076e1a2492f2d61f87aae3f4544b6d0f535ebe33f9fbb6f78710fe1aea8`.
Original engine DLL SHA256:
`3ec41ead011adf56387a6dbd4580e5b5a9721b5f8020c8a56420f42824354943`.
| Original location | Fact and dependency |
| --- | --- |
| EXE VA40E4A0 / raw0E4A0, complete-object virtual offset114 | Positive opacity walks shape polygons and nonnull materials; writes material RGB1, alpha=parameter at +4C..58, source blend enum6 at +30, destination enum7 or1 at +34, and sets flag38 bit0. It does not multiply a previous alpha or scale geometry. |
| EXE VA440000 / raw40000, Init; VA440180 / raw40180, update | Effect initialization and texture changes invoke that setter with0.5. The material opacity applies to all three animated ray textures. |
| EXE global509A13; store VA476BBE / raw76BBE | False selects destination enum1; true selects enum7. Store comes from graphics setup. Complete hardware/settings fallback semantics remain unresolved. |
| DLL VA10036AB0 / raw36AB0; table VA1013667C / raw13667C | Adapter maps blend enums to Direct3D states19/20. Enum6→SRC_ALPHA, enum1→ONE, enum7→INV_SRC_ALPHA. False global therefore means additive SrcAlpha/One; true means conventional SrcAlpha/OneMinusSrcAlpha. |
The DLL REA evidence is
`ev_f5a914ee9eae593b02a04149b6651b2d783151df046bbb417624bf94f23bb96c`,
closed/exported in `artifacts/shrink-ray/rea-blend/00.json`. The parent report
links retained EXE evidence and byte-guard utility. No originals were modified
or executed for this implementation.
## Implementation and explicit policies
`MeshDraw.Opacity` defaults to1; `MeshDraw.Blend` defaults to `MeshBlend.Opaque`.
The other modes are `Alpha` and `Additive`, using exactly the source/destination
factors above for both RGB and alpha. The caller chooses the mode; opacity alone
does not enable blending. The source effect should use opacity0.5 with its chosen
graphics branch. Texture alpha is not pre-halved.
The fragment shader retains the existing texture-alpha cutout test (<0.5) and
then multiplies texture alpha by material opacity. Keeping this test and threshold
is existing port behavior; source alpha-test interaction is still unverified.
The push constant is float opacity at byte64 after the existing64-byte transform;
the68-byte range covers vertex and fragment stages. The vertex shader is
unchanged. Opaque world and opaque UI blend/depth pipeline states are unchanged.
Blended world draws test opaque depth without writing depth. This is an explicit
modern implementation policy: original shrink-ray depth-write state has not been
recovered in this bounded investigation. Rendering order is opaque world,
blended world, then UI; each pass preserves mesh draw order. There is no distance
sorting. UI modes use the same blend factors with depth testing/writing disabled
and the existing identity transform. This supports opacity without disturbing
ordinary HUD composition; it is not a recovered universal original UI contract.
All explicit draw opacities must be finite within0..1 and blend modes must be
valid, including invisible draws. Scene creation/replacement and every render
validate these properties. Per-frame validation runs before swapchain acquisition
or command-buffer recording so a rejected mutable material leaves rendering
usable after correction. All six pipelines are destroyed before their layout.
## Verification
`scripts/compile-shaders.sh` compiled both shaders for Vulkan1.3 and validated
both SPIR-V modules. Vertex SPIR-V remained unchanged. The isolated source-linked
test project builds without compiling the main runtime:
```sh
source scripts/env.sh
dotnet restore tests/GamePort.BlendTests/GamePort.BlendTests.csproj --ignore-failed-sources --source .nuget/packages
dotnet build tests/GamePort.BlendTests/GamePort.BlendTests.csproj --no-restore
dotnet tests/GamePort.BlendTests/bin/Debug/net10.0/GamePort.BlendTests.dll artifacts/gadget-blending/final-frame.ppm
```
Build: zero warnings/errors. Linux headless Vulkan runtime: llvmpipe
(LLVM20.1.2,256bits), Khronos validation enabled, **17 checks passed, zero
validation errors**. GPU RGBA readback checks exercise default opaque color,
half-opacity alpha/additive RGB equations, opaque occlusion, disabled blended
depth writes, UI ordering and depth bypass for both blend modes, zero opacity,
unchanged texture cutout, invalid opacity/enum rejection, and successful rendering
after correction. Numeric color tolerance is2/255 for attachment quantization.
Logs and a final opaque reference frame remain in `artifacts/gadget-blending/`.
These are real port GPU checks, not original-game comparisons. Windows runtime,
the selected graphics-option branch, original depth-write behavior, mixed
transparent scene ordering, and original alpha-test policy remain unverified.
Main-runtime integration and gameplay visual comparison belong to the primary
agent's integration checks.