141 lines
8.4 KiB
Markdown
141 lines
8.4 KiB
Markdown
# 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](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](../checkpoint/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:
|
||
|
||
```bash
|
||
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.
|