GaCy-GO/docs/GACHA-NATIVE-ADAPTER.md

Native per-character Warp adapter

Current Client observation

The enabled presentation configures 76 five-star banners, including collaboration characters. Sending all synthetic IDs in the native GetGachaInfo response caused GachaModule._CmdGetGachaInfoScRsp to throw in the running Client. The server now respects mapped_banner_preview_count (currently zero) even when presentation is enabled; the adapter registers mapped pools separately. The user confirmed Warp opens again, and the Client logged PAGE_BIND ready=76 configured=76. This confirms pool binding, not successful draws or a finished visual layout. Earlier release-gate notes below describe historical checkpoints, not current policy.

Incremental projection, 2026-10-27

Early opening could previously freeze the native collections after only a few of the configured banners had registered, leaving the remainder invisible until the page closed. The adapter now registers at most two configured models per tick and adds at most one missing tab per tick while Warp is open. It checks the page's existing group objects before appending and does not call the native _refresh or select another tab. The latter resets selection.

The append sequence follows the single-pool branch of the current Client's GachaMainPage._create_pools_panel: load prefab, create/bind panel, set its pool and timeout callback, add it to TabControl, then set up its group button. The new content root is inactive until selected. The exact current baked modules were captured read-only; Ui.Component.TabControl.add_item_created does not reference the current selection field. Existing page arrays track the panel for normal disposal. If the native add operation partially fails, there is no proven individual-button removal API; PAGE_APPEND_ERROR reports the tracked failure, and normal page disposal cleans it. Failure to load one supporting four-star portrait leaves the other content visible. Registration failures retry on a later bounded pass rather than permanently suppressing a banner.

This does not replace the native page's initial _create_pools_panel lifecycle: if all pools are already registered before the page opens, that native function may still instantiate those panels synchronously. The new incremental path, its rollback behavior, selection preservation and performance need Client confirmation; Lua parsing alone does not establish those outcomes. Experimental loader scripts have been removed from scripts/ and Frida detached.

Client rank/item coverage — 2026-10-27

The captured AvatarConfig.json and current imported roster contain 76 five-star avatars. Five had previously been excluded because the older external Eidolon resource did not contain their rank rows. Read-only, bounded lookups of the exact AvatarRankConfigExcelTable.GetData rows for those avatars' captured RankIDList yielded 30/30 rows and their UnlockCost; the five distinct cost items were independently retrieved from the current Client's ItemHelper and their ItemRows verified. The companion asset audit also found each avatar's head icon, draw-card splash and result image, and a matching avatar ItemData.

tools/merge_captured_eidolon.py joins the captured IDs to AvatarConfig, checks all six ranks and cost ItemRows, records capture hashes and preserves existing Eidolon entries. The stable-ID generator then retained all 94 earlier identities and added five; all 76 imported five-star avatars now have an active mapping. The custom IDs remain sandbox identifiers, not official banner IDs. These changes did not alter a player's save, inventory, rank, EX state or pity.

Evidence is retained in private battle_diagnostics/ capture logs; the SHA256 digests and captured Client identity are recorded in EidolonConfig.json. The five added banner entries still need native Client registration and draw confirmation after the integrated build is deployed. First acquisition of an avatar absent from the imported roster remains outside this sandbox flow.

Current status — supersedes historical gate notes below

The enabled implementation was built and deployed on 2026-10-25. The Client registered all 71 eligible rarity-five character banners. The user confirmed the prototype's splash art and native panel placement after the opaque overlay was removed. The implementation reuses the generic installed prefab and changes only its owned content; these are custom banners, not restored official assets.

The latest source adds three featured four-star portraits, saved pity labels and the user's requested hard guarantees: featured five-star by 80 pulls and four-star-or-higher by 10 pulls. Shared limited pity and inventory awards commit atomically. Three-star Light Cones come from the captured rarity catalog. The three four-star companions rotate over the imported rarity-four roster; they are sandbox lineups, not captured official banner companions. Base rates are configurable sandbox defaults and are not represented as captured Beta odds.

The 94 stable mappings consist of 71 advertised rarity-five banners and 23 reserved rarity-four mappings. Five avatars lack the required Eidolon conversion config. Registration is confirmed in Client logs; latest portrait layout, draw results/pity persistence, and entering/exiting every new banner have not been confirmed after the latest deployment. AA loading repair is the current gameplay blocker. No tests were added or run for this continuation.

The sections below retain earlier audit checkpoints. Their OFF gate and unproven ItemHelper notes describe those earlier states, not the current policy.

Confirmed foundation

The previous uninitialized-pool approach is superseded. On 2026-10-25 the initialized StandardGachaPoolData / Row / SingleDrawData / MultiDrawData clone was registered through _GachaPoolDatasThisVersion and the native _AddGachaPoolDataToGroupDict using the five-argument reflection Invoke overload with boxed BindingFlags. The Client reported pool=900001 pools=3 groups=3.

Evidence: battle_diagnostics/runtime-continuation-metadata-20261025.log, [GAC_GACHA_CLONE_REGISTER]. Registration proves native lookup/group creation, not correct artwork or draws.

Implementation

• internal/gameserver/gacha_presentation.go validates a policy-selected installed generic template and builds the presentation payload from the stable banner mapping and AvatarConfig.json.
• internal/gameserver/gacha_presentation.lua is embedded behind the policy, outside scripts/. It clones initialized models, assigns the mapped avatar's runtime AvatarName, uses the configured avatar icon, registers native single-pool groups, and hooks only the custom tab's content rendering.
• The new card uses AvatarCutinFrontImgPath. AvatarCutinImgPath denotes a different asset family; do not derive a DrawCard path from that field.
• Art loading uses the native BasePanel _async_load_sprite_to helper captured in .runtime/named-baked-capture/gacha-avatar-panel.json.
• The opaque card is local to the mapped tab's known node_content binder. It does not hide a global Canvas, world camera, phone menu or HUD.
• Registration and installed-asset checks are bounded to two entries per render interval. Actual native group keys are retained for rollback; no group-ID arithmetic or invented enum is used.
• Turning the policy off removes owned clone references after Warp closes. A currently open custom card is not removed mid-draw.
• The same mapping is accepted by DoGacha; when native presentation is enabled, GetGachaInfo advertises the full active mapping as well.

Current release gate

resources/GachaSandboxPolicy.json has native_presentation.enabled=false. Do not turn it on solely because the Go binary compiles. Verify the single-banner card's constructor/binder, displayed avatar art/name and draw 1/10 behavior in the Client first. No tests were added or run.

There are 94 mapped avatars. Five imported avatars have no configured first Eidolon conversion and remain outside this sandbox mapping. First acquisition of an absent imported avatar is still rejected. This is a custom featured sandbox presentation, not restored official limited prefabs.

Controlled runtime tools

tools/build_gacha_presentation_probe.py --output <file> renders one banner by default. It never stages a script, changes policy, or writes a save. --limit 94 --assets-only emits only a bounded AssetMgr.Exists capture under a separate global configuration name; it does not register pools or UI.

tools/gacha_item_data_probe.lua reads exact ItemData constructor and ItemHelper.GetItem metadata. The ItemHelper return type needs confirmation before relying on it as a native ItemData array element. The adapter now resolves the exact static GetItem(UInt32) reflection overload and rejects a return type that is not assignable to the captured native ItemData array element. It then checks the actual returned instance and ConfigID before mutating native pool collections. This is a runtime guard, not evidence that the current Client has that overload.

The staged one-banner adapter is a runtime adapter with an onBeforeRender callback. When finished, close Warp and send _G.__GAC_GACHA_PRESENTATION={enabled=false} to remove owned clones, then remove the staged file. A production heartbeat with the disabled policy supplies the same cleanup signal.

Integration

The caller appends loadGachaPresentationLua() to PlayerHeartBeat.DownloadData, logging a presentation error without failing unrelated heartbeat callbacks. The function reads external resource policy, so an operator can disable it without replacing saves or executables.

Unknown at this checkpoint: the new card has not yet been Client-confirmed; callback failure must not be described as a working banner. Native registration is confirmed separately from presentation, asset availability, and successful draws.

Offline adapter audit, 2026-10-25

These source changes were made without staging a probe, changing policy, running tests, rebuilding or restarting servers:

• Rendering now destroys the newly created opaque card if a later binding or sprite-request call throws. The previous path logged the exception but retained an untracked overlay. This covers synchronous setup failure; it does not prove the later asynchronous sprite request succeeds.
• Disposal explicitly destroys the owned card. No global Canvas, camera or unrelated page object is touched.
• Rendering hooks match the exact owned pool instance as well as its configured ID. A foreign extension's pool with the same ID must not be repainted as this adapter's character.
• Each hook captures its original callback locally. Replacing the mutable originals table on a later policy revision can no longer make a retained older wrapper delegate recursively into a newer wrapper.
• Native pool/group collections are frozen while the Warp page is open. Configuration changes, disabling, and registration reconciliation wait for the page to close; the selected pool is not removed during a draw.
• A new configuration digest removes the previous owned projection before installing a replacement. Cleanup also removes the exact owned group from the native cached group list and clears a selected-pool cache only when it refers to the removed clone. It does not remove unrelated groups or derive native group keys.
• Re-registration after a native GetInfo refresh removes that banner's stale owned references before creating its replacement. Registration rollback also removes newly created cached group entries.
• The Go payload and controlled-probe builder include the adapter source in the digest. A new server executable with unchanged banner data can therefore replace its older owned hooks after Warp closes, instead of keeping old closures for the whole Client process.

The release gate remains OFF. Still required before enabling:

1. Current-process evidence for ItemHelper.GetItem(UInt32) and the actual returned ItemData; old MethodHandles and native addresses are invalid after a Client restart.
2. One-banner card proof for node_content, text cloning/SafeSetTextID and the _async_load_sprite_to(image,path) call, including successful asynchronous art completion. A bytecode call site or ART_REQUESTED log alone does not prove the image appeared.
3. Native response/refresh lifecycle proof: synthetic IDs can be skipped before original pool construction, and the custom registration must remain consistent when GetGachaInfo refreshes the module. Merely registering an initialized clone once is not evidence for every refresh.
4. Draw 1/10 result/display behavior with the mapped avatar and configured duplicate materials, plus close/reopen behavior. No assertion of Client success should be made from compilation or native registration alone.

Current source has not been compiled or Client-exercised after this offline audit. All custom banner IDs remain the explicit resource-backed sandbox mapping; no additional game IDs, asset paths or group enum values were invented.