Files
Neutron/docs/gameplay/bubble-rendering.md

8.4 KiB
Raw Permalink Blame History

Bubble sprite implementation and rendering boundary

2026-11-02. Implements the owned visual component and original resource export. Equip/body/input integration belongs to the primary runtime change. This report establishes source recovery, asset identity and managed checks; it does not claim original Bubble execution, exact original sprite orientation or native Windows runtime verification. Originals remain read only, with539 unchanged hashes.

Source and additional REA evidence

bubble.md retains the authoritative410840/410AE0/410CA0/410D00 contract, source spans, virtual bindings and REA limitations. EXE SHA256 is f5281076e1a2492f2d61f87aae3f4544b6d0f535ebe33f9fbb6f78710fe1aea8. Additional local Ghidra12.1.4 queries used the same generated copy, exported complete Evidence and closed/snapshotted under artifacts/bubble/rea-rendering-ipc/:

Procedure Evidence ID Observation
4352F0 sprite base ev_7ea79d719ffb701f10a497f5790384aa56801d970a34ea7ecd4152052ac8f8df Calls463F10; sets complete+C8 game interface; temporarily sets flagC4 bit1.
4645F0 InitSpriteProperties ev_ab13438ec345f10472d10965048c34d31654e6d9303d729df98b65aa92d37a1e Writes AC/B0 supplied size, WORDC4=1, alignmentBC/C0=3, blend6/7. Graphics flag true writes RGBA(.9,.9,.9,1).
464210 preparation ev_4d39cc1aaad564de60bb801c08dfeb740d52e507227e630de9b0570e3e1bc43d Calls458910, forwards root/Euler to virtual setters, calls479A40; does not recover camera-facing drawing.

The initial sandbox attempt is retained in rea-rendering/; Ghidra imported successfully but could not bind its local Unix socket (Operation not permitted). The allowed local IPC retry above succeeded. That initial batch supplies no successful decompilation Evidence; no original code was executed in either.

Supplementary objdump output and independently mapped source-span hashes are in artifacts/bubble/*-rendering.asm and rendering-spans.json. End VAs are exclusive:

VA range File offset / bytes SHA256
4352F0..4353BF 352F0 /207 ee18deb9d0492ee3d921e99d56edea9eb11fc4b28bdbc171ee398a6628a41834
4645F0..4646B8 645F0 /200 1e666182de97533be5e917b5763957ce148bceb831b05061df19ccd89d3bae28
464210..46429F 64210 /143 a99be3694789b6b6284b7e171eec0f2f26b59eef6a366265646bf6c8cbd92000

Constructor410978 supplies200 to4645F0 before overriding blend to6/1. Start changes destination to1 or7, with no color reset. The optional conventional graphics branch therefore starts with(.9,.9,.9,1) before its first fade update; the default additive branch retains white. Active conventional rendering writes (1,1,1,.5), while default additive rendering retains the previous RGBA.

Assembly410AEC..410AF2 adds dt and stores a float timer without popping the x87 sum. The expansion comparison410B95 and collapse subtraction/comparison410C12.. 410C1E use that unrounded sum. BubbleEffect.Step retains a double addition for those boundaries while storing Timer as float. The active pulse reloads stored Timer at410B4C. A managed test covers Timer rounding to1 while the strict source comparison has already crossed1. Math.Sin is a numeric projection; x87 fsin bit parity and whole-game timing remain unverified.

Callback ordering

Jimmy42232C constructs Bubble410840; its410892 call enters4352F0, whose435341 call enters463F10. The independently established chain in lab-registry.md continues463F6C complete+C8 → 4586F0 →46FBE0 → tail insertion. Together with the owned effect slot3C4→410AE0, this supports fresh-game input → Jimmy → Bubble update as a partial order, with other registered helpers allowed between them. The owned fire registers earlier during Jimmy's base construction. The source registry, not source60Hz, establishes that relative order.

Retained Bubble survival, teardown flags and update eligibility have not been independently traced here. Reusing the same owned component across ordinary Jimmy retention, and scheduling Jimmy → Bubble → newly appended game input, remains an integration inference until that helper lifecycle is closed. The modern fixed-step cadence is a separate port policy. Do not gate visual time on raw input ownership merely because placement/drain happen in controlled input.

Assets and exported format

tools/extractors/bubble_resources.py resolves the archive case-insensitively, validates its complete hash, unique Canv1 metadata, payload and decoded pixels before writing. It rejects outputs in/above originals and preexisting output file symlinks. Export contains no generated sphere or recolored image:

python3 tools/extractors/bubble_resources.py ../Original \
  --output artifacts/extracted/bubble

bubble.json schema1 contains source, archive sourceSha256 and exactly one textures record with id/name/width/height/path/png/sourceOffset/sourceBytes/ sourceSha256/rgbaSha256. canvas_1.rgba and canvas_1.png retain the original 146×146 image, including5492 alpha0 and15824 alpha255 texels.

  • Archive SHA256: b584ffa4a38f4bc809b3ea8f4321e0c08f2719e22df41a3fb4cd143ed89b3bef.
  • Payload offset17FCE/66322 bytes, SHA256: 9b6cdce95bd408fa1dc806d30520df65971f25d1663ab8da4ca6bf41380805ec.
  • Decoded RGBA SHA256: a3a678c47c1ce94946b1136560a84f3ef86c6884b981256a9fbff62fe8a988e4.

Implemented renderer and explicit policies

BubbleEffect owns independent Active/Expanding/Collapsing/Visible flags, Timer, full Vector4 Color and dimensions. Start() only sets expansion/visibility and resets Timer. Stop() is the original leaf and deliberately preserves expansion; Jimmy cleanup must additionally call ClearExpansion(). Active beats expansion, which beats collapse. Fade does not change size; the first active invocation changes200×200 to240×(240+sin(timer*10)*30), retaining the last pulse size during collapse. Exactly1 remains expanding; exactly zero fade remains collapsing and visible. A subsequent negative fade hides it. Reset() reconstructs initial owned visual state rather than pretending to be the original Stop leaf.

BubbleVisuals(Mesh combined, string preparedRoot) loads bubble/bubble.json, bounds its manifest/pixel sizes, validates the original pixel hash and appends four vertices/six indices. It preserves existing draws/textures and collision metadata. Update(destination,effect,root,eye,target) receives the already captured source BubbleRoot; it applies no extra Jimmy scale or root offset. RGB multiplies all four vertex colors; alpha goes through MeshDraw.Opacity. Default blend is SRC_ALPHA/ONE; optional graphics mode uses SRC_ALPHA/ONE_MINUS_SRC_ALPHA. Current Vulkan blended world draws test existing opaque depth without writing depth.

The quad is centered on root and uses the same camera-facing basis as the existing scene sprite adapter: direction=normalize(target−eye), right from worldUp×direction, up=direction×right, with deterministic degenerate-camera fallbacks. Width/height are complete world-space edge lengths; UVs cover the complete original image. This basis, centered interpretation, modern UV0..1, filtering/alpha-cutout behavior and depth-write policy remain modern rendering boundaries. Alignment3/3 is recovered, but complete original engine alignment scheduling, local-axis orientation, camera roll, render-state ownership and zero-length original placement normalization are not closed. The result must not be described as original visual parity without comparison.

Validation

  • Five Python checks pass: exact archive/resource/decoded PNG identity, output separation, child symlink protection and rejection before writing on bad archive/dimensions/pixels.
  • Eight managed effect/visual groups pass: strict boundaries and full RGBA, pulse/graphics branches, Stop priority/cleanup, unrounded fade comparison, independent clocks/reset, original quad/material/metadata, camera degeneracy and malformed/path-traversing/altered resource rejection.
  • Main dotnet build --no-restore passes with zero errors; cached NU1900 vulnerability-feed warning is unrelated to this change. All539 original hashes verify unchanged. Logs: artifacts/bubble/visual-validation/.

Commands: python3 -m unittest discover -s tests -p test_bubble_resources.py -v and source scripts/env.sh; dotnet run --project tests/GamePort.BubbleVisualTests. Managed/asset checks and compilation do not establish GPU rendering, original runtime comparison or Windows execution. Primary integration owns those results.