Skip to content

feat(il2cpp): inventory Unity IL2CPP global-metadata images, types and methods - #3807

Merged
gensokyo-dev merged 25 commits into
morluto:mainfrom
8rulerstar:feat/il2cpp-metadata
Oct 19, 2026
Merged

gensokyo-dev merged 25 commits into
morluto:mainfrom
8rulerstar:feat/il2cpp-metadata

Conversation

@8rulerstar

@8rulerstar 8rulerstar commented Oct 15, 2026 •

Copy link
Copy Markdown
Contributor

Outcome

Report the validated header magic/version and decode image, type and method names from a caller-selected Unity IL2CPP global-metadata.dat (versions 29, 31 and 39), without Unity or a native analysis engine. Preserves the original implementation and author history from this PR; follow-up commits add composable queries, bounded delivery and lifecycle fixes. Closes #3784.

  • MCP defaults to compact counts while retaining complete artifact-bound Evidence. Query sections/images/types/methods by stable source index, exact names, batch indices, owners, image or namespace; select fields and page filtered matches. Source indices remain distinct from page offsets, with provenance, coverage and unknowns preserved.
  • CLI defaults to complete Evidence. Compact CLI delivery requires an explicit new Evidence file and never overwrites it. Shared JSON readers/writers preserve filesystem path selection through symlink-parent traversal and directory requirements. Desktop discovery emits a supported-metadata follow-up even without a native library. CLI/MCP share inspection and view semantics.
  • One active inspection per reader; cooperative decoding, owned cancellation and awaited cleanup. Count UTF-8/JSON expansion before serialization and preserve completed source Evidence through descriptor-close failures and cancellation. Retained immutable facts share validation/counts without cloning another cached report.

Validation

Executed locally on Linux with pinned Node 24.18.0: npm run check, npm run docs:check, 100 focused tests across 12 files on 5f65d4adb, and the public CLI/MCP producer verifier. Earlier decoder/view/service/counter coverage passed 115 tests, plus 27 shared JSON-input/cancellation tests after integrating main 7a0c47bfa. Test discovery found every file exactly once. Actual stdio SDK tests validate advertised schemas after conversion and each output.

Real compiled CLI tests cover compact/default and complete delivery, retained reads after source removal, all four collections, filters/batches/fields, exclusive export, and POSIX symlink-parent export/readback with an unrelated decoy preserved. Controlled close faults on real files verify completed source Evidence, original cancellation reasons, retained descriptor ownership and Evidence after cleanup retry; failed reads fabricate no source facts. Codex review was unavailable because the repository review quota is exhausted. Greptile's export-selection and completed-source findings are corrected in this follow-up.

Public producer: Cpp2IL Simple_2022_3_35 at b5ad444, raw metadata v31, 1,892,268 bytes, SHA-256 2441635a7c234a1a34deccc6a9906d6f5abcbdab078a38b2bf488a52a4962c48. An independent raw-byte oracle matched every exposed field across 36 images / 2,468 types / 12,409 methods. Corresponding managed DLLs independently matched names and ownership for 35 images / 2,463 types / 12,406 methods; generated rows have no corresponding DLL and use the byte oracle. No target execution. Versions 29/39 have synthetic coverage here; the original author's five private Unity-build comparisons are historical evidence and were not repeated locally.

Measured task costs

Actual compiled stdio SDK task: find GameObject.SendMessage and Transform.GetChild in CoreModule, then retrieve both facts again after removing the owned input copy. Both paths assert equal facts, SHA and Evidence linkage. Baseline uses explicit summary and the smallest available range queries. Two alternating pairs, baseline original PR integrated at main b4938aed5, follow-up integrated at main 7a0c47bfa; concurrent main changes are included. Fresh processes, 2 CPUs, bounded heaps, compile caches disabled; OS caches and host load uncontrolled.

Cost Baseline 055b8787a Follow-up f8fce575f
Tool calls 7 5
Selected declarations + all calls/replies, tokenx estimate 96,743 22,137
All input declarations + calls/replies, tokenx estimate 314,912 240,306
Entire recorded JSON-RPC exchange, tokenx estimate 1,074,308 1,000,515
Whole task elapsed 4.71–4.84 s 4.60–4.66 s
Whole process-family CPU 5.89–6.06 s 5.77–5.78 s
Sampled peak process-family RSS 719–746 MiB 726–731 MiB

Includes discovery, schemas, protocol envelopes and output validation; build/install excluded. Actual model/host-rendered context tokens are unmeasured. Earlier pairs varied with host load; no consistent speed or memory improvement claimed. First source inspection/first retained view and warm retained queries are recorded separately; the final lookup succeeds without source access. The final header field is included in the measured schemas and replies.

After the boundary fixes and main bf1eeee94 integration, the complete five-call task passed again: 22,210 selected-declaration/call tokens, 240,379 all-input-declaration/call tokens, and 1,000,596 entire-protocol tokens (all tokenx estimates). One final run measured 6.69 s elapsed, 7.67 s process-family CPU and 713 MiB sampled peak RSS. The paired table pins its earlier revisions; this final correctness/cost probe includes the subsequent main changes and is not a speed comparison.

Scope and limitations

Repository-operator authorization covers this static metadata slice and ready-for-review follow-up. No execution, injection, decryption, protected recovery, native address linking or disassembler integration. Fields/signatures/runtime loading and correspondence to GameAssembly remain unknown. Input guard 256 MiB; encoded retained report guard 64 MiB, separate from MCP transport capacity. Optional CLI export writes only the caller-selected Evidence output.

The original author's initial readiness declaration is retained below; later pushes do not require another initial declaration. It is not an assertion of a new human review of these follow-ups.

Author readiness

Human owner: @8rulerstar

  • I reviewed the final diff and relevant existing code, understand the change and its edge cases, and take responsibility for the complete PR, including AI-assisted work.
  • I checked the evidence above, confirmed it supports the current change, and recorded meaningful validation gaps.
  • I declare this PR ready for initial maintainer review.

@matbrgz

matbrgz commented Oct 15, 2026

Copy link
Copy Markdown
Contributor

Nice to see it, please go ahead and implement all unity.

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 15, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ⚠️ Failed 2026-10-19T21:44:01.003024Z f8fce57 Manual request
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@greptile-apps

greptile-apps Bot commented Oct 15, 2026 •

Copy link
Copy Markdown
Contributor

RetriggerView in GreptileConfidence Score: 5/5

[Medium impact] The PR appears safe to merge; no new actionable issue was established.

Summary

Adds static Unity IL2CPP metadata inspection for versions 29, 31 and 39.

  • Unity metadata files now show their image, type, and method names.
  • Callers can page and filter retained metadata without rereading the file.
  • Desktop discovery now points supported metadata files to the right inspection tool.
  • Compact CLI results can keep their full Evidence in a new selected file.
  • Metadata reads now stop cleanly and keep source facts through cleanup.

The ancestry check passed, but the merge bases differed, so this review used the full PR diff. All supplied previous threads were unnumbered and were treated as context rather than numbered findings.

No tests were executed during this review. GitHub authentication was unavailable, so supersession could not be checked remotely.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  A[Selected metadata file] --> B[Stable bytes and SHA-256]
  B --> C[Check header and decode rows]
  C --> D[Complete Evidence]
  D --> E[CLI complete output or exclusive export]
  D --> F[MCP retained Evidence]
  F --> G[Summary and filtered pages]
Loading

Reviews (18) · Last reviewed commit: "chore(il2cpp): integrate current scenari..." · Reviewed by Greptile

Comment thread src/il2cpp/Il2cppMetadataProvider.ts Resolved
Comment thread tests/fixtures/il2cpp/metadata.ts Resolved
@8rulerstar
8rulerstar force-pushed the feat/il2cpp-metadata branch 2 times, most recently from ed34f7c to b7c1800 Compare October 16, 2026 02:19
@greptile-apps

greptile-apps Bot commented Oct 16, 2026

Copy link
Copy Markdown
Contributor

Want your agent to iterate on Greptile's feedback? Try greploops.

Comment thread scripts/verify-il2cpp-metadata.mjs Resolved
Comment thread scripts/verify-il2cpp-metadata.mjs Resolved
@8rulerstar
8rulerstar force-pushed the feat/il2cpp-metadata branch from daf9ab7 to 931e4a3 Compare October 16, 2026 05:01
Comment thread src/il2cpp/Il2cppMetadataProvider.ts Resolved
Add inspect_il2cpp_metadata (CLI inspect-il2cpp-metadata), a read-only
in-process decoder for unencrypted Unity global-metadata.dat version 39.
It reports header sections, serialized index widths, images, type
definitions (nesting from the nestedTypes section) and method names.

Unrecognized magic and other versions are unsupported; damaged headers,
overlapping sections, inconsistent record sizes, out-of-range indices and
invalid strings fail with a reason code and no partial success. MCP
detail summary retains the complete Evidence and pages rows through
inspect_analysis_view kind il2cpp-metadata.

Adds an opt-in verify:il2cpp:metadata -- --metadata PATH check.
A 112,232-method file produced a 10.5 MB complete response, above the
10 MiB stdio budget. Default MCP delivery is now the retained summary;
detail complete stays available, and the one-shot CLI requests it.
…drift

Review fuzzing showed that moving the strings section offset by one byte
silently renamed every image, type and method. Name indices must now start
a string, which also bounds total decoding by the section size.

Nesting cycles and methods whose declaring type disagrees with the owning
type range are rejected instead of returned. Adds service, shutdown and
index-width coverage, and moves environment-specific measurements out of
the public guide and tool description.
Unity 2022.3 writes version 29 or 31 metadata: a 256-byte header of
(offset, size) pairs, fixed 4-byte indices, type records with
elementTypeIndex, and method records that gained returnParameterToken in
version 31. Record counts come from section sizes and must be whole.

Sections report a null count for these versions and index widths report
fixed-width-version. Image, type and method rows keep the same shape, and
the string, nesting and method-ownership checks apply to every version.
Rows share decoded names, so a 130 KB file could expand into gigabytes of
JSON before the 64 MiB budget check, ending in an internal RangeError. The
provider now refuses from a lower bound on the serialized rows first.

The decoder also rejects non-empty sections inside the header, methods
outside their declaring type's range and overlapping image type ranges, and
keeps a leading byte order mark in names. Layouts now carry one indexing
mode instead of two coupled flags, and the tool description explains
nested_type_start.
Address review findings on the IL2CPP metadata inventory:

- check a lower bound from header row counts before any row object is
  allocated, so a large rejected file no longer builds every row first;
- validate sealed parent Evidence and count its rows once per report
  instead of on every inspect_analysis_view page;
- decode version 39 fixtures with 2- and 4-byte type-definition,
  generic-container and parameter indices.
…on tools

inspect_il2cpp_metadata defaulted to detail summary, the only inspection
tool to do so. Omitted detail now returns every row inline, as
inspect_artifact, decode_interface_builder and the capture tools do;
summary stays one argument away and the guide, CLI reference and skill
reference say to select it first for large games, whose complete MCP
delivery is refused at the stdio budget with retained Evidence.
…ault

An empty image stores its type start as the all-ones value of a one- or
two-byte index; the decoder reads it as -1, but no fixture exercised it,
so removing either conversion passed the suite. The fixture can now append
an empty image, and both widths decode it. The skill still described a
summary default; it now says to select summary first, as the guide does.
@8rulerstar
8rulerstar force-pushed the feat/il2cpp-metadata branch from bc1f3be to 16a0109 Compare October 19, 2026 02:57
Comment thread scripts/verify-il2cpp-metadata.mjs Resolved
8rulerstar and others added 5 commits October 19, 2026 12:22
Use absoluteCallerPath (morluto#4067) so a path with a symlink followed by .. names the same file the CLI and MCP inspect.
Retain source-indexed Evidence for filtered batch and field queries. Bound representation growth before serialization, yield decoding for cancellation, and share CLI Evidence publication with desktop inspection. Verify public Unity metadata against independent byte and managed-DLL oracles and exercise actual stdio SDK workflows.
@gensokyo-dev

Copy link
Copy Markdown
Collaborator

@codex review

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex usage limits have been reached for code reviews. Please check with the admins of this repo to increase the limits by adding credits.
Repo admins can enable using credits for code reviews in their settings.

Comment thread src/cli/analysisEvidenceDelivery.ts Resolved
Comment thread src/il2cpp/Il2cppMetadataProvider.ts Resolved
@gensokyo-dev
gensokyo-dev merged commit 8331365 into morluto:main Oct 19, 2026
47 checks passed
@github-actions github-actions Bot mentioned this pull request Oct 19, 2026
3 tasks done
kangyishuai pushed a commit to kangyishuai/rea that referenced this pull request Oct 19, 2026
…ansition-view

Resolve conflicts with main's il2cpp-metadata view (morluto#3807) by keeping both
view kinds: the analysis-view request and result unions, parent
operations, summaries, unsigned view types and the tool description now
cover the il2cpp-metadata and browser-scenario views. The generic
unsupported-parent message names both, and the unreachable
browser-scenario fallback stays removed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@8rulerstar
8rulerstar deleted the feat/il2cpp-metadata branch October 20, 2026 00:24
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Feature] Read-only inventory of Unity IL2CPP global-metadata.dat (first slice of #3607)

3 participants