Skip to content

feat: add experimental TMNT Mac and iPad source host - #2125

Open
HaomingJu wants to merge 1 commit into
ly05010419:mainfrom
HaomingJu:tmnt
Open

HaomingJu wants to merge 1 commit into
ly05010419:mainfrom
HaomingJu:tmnt

Conversation

@HaomingJu

@HaomingJu HaomingJu commented Nov 12, 2026 •

Copy link
Copy Markdown

Summary

Adds an experimental Apple silicon Mac host and iPadOS target for Teenage Mutant Ninja Turtles: Shredder’s Revenge, exact base 1.0.0 (0100FE701475A000). The build verifies the player’s own NSP/XCI and keys; game data, keys, saves, generated code and translated shaders are not contributed.

The Mac host now includes Simplified/Traditional Chinese catalogue support, a 1-key settings panel for frame-rate targets, input, window size/full screen and save-folder sync, and a stable MacNativeGames/TMNT profile. The first launch copies the newest legacy hash-named profile without overwriting stable saves or removing the original. iCloud Drive uses the shared local-copy/generation/conflict-backup model; actual cloud delivery remains the responsibility of iCloud Drive.

Review changes

  • Shared pinned SPIRV-Cross and codec dependencies; embedded stb_vorbis instead of mandatory external Vorbis/Ogg. iPad codec sources, CMake/Ninja and documented XcodeGen come from tools/deps.
  • Pending render-target clears are flushed before DrawTexture. A Metal pixel regression exercises ClearColor → DrawTexture → submit without an intervening draw.
  • The container build entry, Launcher recognition, installed-App detection, recorded/default work-folder rule and runtime-only update planning are connected. Full builds retain existing work files and publish into the same installed App directory.
  • Separately signed shader data; 80 shaders extracted/translated privately; parallel pipeline archive creation and fresh-process checks against the exact shipped warm-up list. Warm-up finishes before title display. Digest/signature reuse and runtime-only updates preserve immutable data. All nine TMNT packaging exemptions are removed, with behavioral checks added.
  • Provenance inventory and packaged third-party notices are updated. The pipeline list and contribution collector use TMNT’s own identity.

Build from the repository root:

python3 games/tmnt/build.py '<base game.nsp or .xci>' --keys '<prod.keys>' \
  --work '<private work folder>' --out '<private output>/TMNT.app'
python3 update_runtime.py '<private output>/TMNT.app' --plan

See Mac instructions and iPad developer workflow.

Validation on this revision, 2026-11-16

Local validation: 61 TMNT tests, 7 packaging-standard checks, 3 no-Homebrew checks, 7 work-folder checks, and 10 dependency-helper checks passed. Selected Launcher, shader contribution and collector checks also passed. The Metal clear/copy pixel probe passed 256 channel comparisons; the frame-pacing probe passed 120 cases. The complete build.py entry succeeded from the player’s original NSP/keys in a nonempty work root, with fresh extraction/rewrites and external link validation. The installed App directory was retained. update_runtime.py --plan selected an express update using that recorded work root; the actual update succeeded, preserved the game hash and every signed shader-bundle file, and passed deep/strict code-signature verification. The launcher directs the RomFS verification cache to the external profile; a post-launch seal check caught and corrected the inherited in-bundle cache write.

After the complete build and express update, a final muted relaunch retained Traditional Chinese, reached the story menu and closed with exit code 0; deep/strict signature verification still passed afterward.

A muted Mac run rendered Simplified and Traditional Chinese menus, switched languages, saved the option, restarted across a runtime update, and entered chapter 1 with keyboard movement/attacks. Chapter-1 samples at the 60 target were approximately 59–61 FPS; the experimental 120 target mostly reported 119–121, with a late 107 sample around screenshot/exit. This measures submitted game frames, not proof of correct 120-FPS simulation speed or visible unique frames on every display. The earlier real-time scheduling policy was observed demoting the renderer; the host now defaults to interactive QoS. The earlier 2-second encode-drain abort did not recur in this bounded run; its complete root cause and long-session stability are not established. Original user save/account bytes remained unchanged; tests used copies.

Remaining limits / coordination

  • Website inbox: client and collector use only tmnt. Automatic upload is disabled until the maintainer registers TMNT in the separate website service and supplies the route. That repository was inaccessible to this contributor; no server deployment or successful upload is claimed.
  • The warm-up list covers observed title/menu/chapter-1 states, not every chapter. Unseen states may compile during play.
  • 120 FPS is experimental. Full chapter coverage, sustained play, audio listening quality (tests were muted), and cross-device iCloud transfer are not validated.
  • iPad codecs cross-build with pinned tools on a PATH containing only Apple/system tools. This revision has not been fully rebuilt, signed and run on an iPad; earlier private-device observations are not current-revision validation.
  • The inherited broad probe-gfx still stops at its hard-coded TOTK NVN ABI expectation (55 versus the host’s advertised 53); it is not reported as passing. The dedicated new GPU/pacing probes above pass.
  • Only the exact supported base image is accepted; updates/DLC are unsupported. Local checks do not imply that all remote CI/review checks passed.

Provenance and licenses

tmnt-import.json records copied-file origins/commits and current digests. COPIES.md and the root notices retain the upstream licenses. Generated private packages carry these notices and dependency licenses.

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 12, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ❌ Failed

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

Review Status Commit Review trigger
📝 Code Review ❌ Failed 2026-11-16T08:05:34.887259Z
We couldn’t complete this review. Comment @codex review to try again.
c5b4b9e Draft marked ready
ℹ️ 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.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 293317bb60

ℹ️ 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".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread games/tmnt/runtime/audio_renderer.c Resolved
Comment thread games/tmnt/runtime/audio_renderer.c Resolved
Comment thread games/tmnt/scripts/package_private.py Resolved
@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Something went wrong. Try again later by commenting “@codex review”.

Failed to sample tokens
ℹ️ 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".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

@ly05010419

Copy link
Copy Markdown
Owner

Thank you for bringing TMNT up as its own target. Before we can merge, please change:

  1. SPIRV-Cross: games/tmnt/third_party/spirv-cross bundles ~78k lines of source at aa217aeb. The repository builds spirv-cross from one pinned source through tools/deps (it reaches GitHub's main with our next push) (tools/deps/pins.py, currently 1.4.363.0 / f11ba9f0); please use that instead of a copy.
  2. No Homebrew: the Makefile finds opus, libvpx, libvorbis and libogg through pkg-config (lines 16–18), which in practice means Homebrew. Players should not need Homebrew; take the codecs from tools/deps, and tests/test_no_homebrew.py will check it. The runtime already carries stb_vorbis — why are libvorbis and libogg needed as well?
  3. Build entry: there is no games/tmnt/build.py, so tests/test_packaging_standard.py does not see this game, and the build needs a hand-extracted exefs/romfs. Please give it a build.py like the other games (build from the player's game file and keys) and register it in the packaging standard test, with its gaps listed.
  4. Provenance: please add games/tmnt/third_party/tmnt-import.json (origin and commit of every copied file) so tests/test_provenance.py checks it, as the other games do.
  5. README: the "What's new" line says 2026-11-09 and sits out of date order.

Also, the results in the description come from earlier private builds; please run this revision once on the Mac and say what you saw.

@chatgpt-codex-connector

Copy link
Copy Markdown

💡 Codex Review

https://github.com/ly05010419/MacNativeGames/blob/30e8b4179c4570543e2d1f68ca5b79bba8688bfc/games/tmnt/third_party/d2r_gfx/gfx/nvn/nvn_mtl.m#L12713-L12714
P2 Badge Flush deferred clears before copying with DrawTexture

In the shared Mac/iPad renderer, when a full-target ClearColor is followed by DrawTexture without an intervening ordinary draw, the clear remains pending in R.clear_c. This branch calls copy_t2t_scaled(), which only calls rp_end(); with no open render encoder, that leaves the clear pending. Consequently, mtl_sub_commit() calls rp_flush() and encodes the clear after the texture copy, erasing the fullscreen image. Flush pending clears before this copy, as the existing copy_t2t() path does.

ℹ️ 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".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

@HaomingJu
HaomingJu marked this pull request as draft November 13, 2026 12:31

Copy link
Copy Markdown
Owner

Reviewed 195363d2d607000e989c271013ca1fe7c7698f03. The previous requested updates are now present: shared SPIRV-Cross and macOS codec dependencies, the container build entry, packaging-standard registration, the provenance inventory, and the README date correction. The audio-table fixes, external game-slot directory and iOS publisher executable bit are also present.

Please address the following before merging:

  1. Keep saves independent of the runtime binary. package_private.py:44 puts the runtime SHA-256 prefix in TOTK_PROFILE_DIR. Generating launchers with two different runtime hashes selects two different persistent profiles; fs_host.c reads saves from those profiles. Rebuilding the host therefore makes existing progress appear missing, although the old files remain. Use a stable game-specific profile, preserve/migrate existing saves without overwriting them, and version only rebuildable caches when needed. Add a regression check that changing the runtime preserves access to the same save.

  2. Flush pending clears before DrawTexture. The OP_DRAW_TEXTURE branch still calls copy_t2t_scaled() directly. That helper only calls rp_end(); when no render encoder is open, a pending full-target clear remains in R.clear_c. Submission later calls rp_flush(), placing the clear after the texture copy. The ordinary copy_t2t() path already flushes first. Fix this ordering and add a pixel-result regression for ClearColor → DrawTexture → submit, including the no-intervening-draw case. This is the earlier review finding, still present in the current head; our latest check was source analysis, not a GPU pixel reproduction.

  3. Implement the packaging requirements, rather than only registering exemptions. The standard test currently lists nine gaps: separately signed shader data; parallel pipeline-archive creation during packaging; warm-up completed before the title; build checks executed outside the new App; digest reuse; retaining the installed App directory; runtime-only updates; warm-up lists beside the shader map in build/; and checking that the archive was built from those exact lists. build_private_bundle.py still runs its link check inside the assembled App and requires fresh work/output directories. Complete these paths with behavior tests, then remove the corresponding exemptions. Current main includes the SS integration from feat(ss): The Legend of Zelda: Skyward Sword HD 1.0.1 as its own Mac target #2093 as a reference for shared packaging helpers.

    Also connect TMNT to MNG Launcher/tools/mng.py, installed-app detection and update_runtime.py --plan, using the common recorded/default work-folder rule. Adding a standalone build.py alone does not make Launcher recognize or update this title. Coordinate the TMNT-specific website inbox/uploader/collector route; do not submit its records under another game's ID.

  4. Finish the iPad dependency/tool integration. ios/tools/build_deps.py still invokes ambient cmake/ninja, and the documented workflow invokes an ambient xcodegen. Provide these through the repository's pinned dependency/tool helpers. Validate the documented entry from an environment without Homebrew tools on PATH; macOS dependency changes alone do not establish this for iPad.

  5. Update the remaining documentation and validation. The root THIRD_PARTY_NOTICES.md still names the removed TMNT SPIRV-Cross directory and old aa217aeb revision. Correct the paths/version and retain the required notices in generated packages. Investigate the documented encode stage did not drain in 2 s abort and rerun the interrupted language-switch/save/restart checks on the revised build. Report what was actually tested, including any remaining iPad limitations.

Local review checks passed: 45 TMNT source/native CPU-probe tests, 15 selected shared checks scoped to the exported review tree, and Mac/iPhone SDK syntax checks of nvn_mtl.m. These are not a full repository regression, complete app build, gameplay test or iPad device validation. Passing the packaging test with exemptions does not mean the missing requirements are implemented.

Please also update against current main: tests/test_packaging_standard.py now conflicts with the SS registration. Preserve both games' registrations when resolving it.

@HaomingJu
HaomingJu marked this pull request as ready for review November 16, 2026 03:46
@HaomingJu
HaomingJu force-pushed the tmnt branch 2 times, most recently from 31386ca to e8bcb3b Compare November 16, 2026 03:55
@HaomingJu
HaomingJu marked this pull request as draft November 16, 2026 06:29
@HaomingJu

HaomingJu commented Nov 16, 2026 •

Copy link
Copy Markdown
Author

Addressed the follow-up review in c5b4b9e9 (rebased on current main, one contribution commit):

  1. Persistent profile: launchers now use MacNativeGames/TMNT; migration copies the newest legacy save/account/settings and retains originals. Existing stable profiles are never overwritten. A two-runtime-hash launch regression checks the same save remains accessible.
  2. Clear ordering: DrawTexture flushes pending clears before copying. The actual Metal command-stream pixel probe passed all 256 channel comparisons for clear → texture copy → submit with no intervening draw.
  3. Packaging/Launcher: implemented the nine paths and removed the exemptions, preserving SS registration. Shader data is independently signed; pipeline creation is partitioned and checked in fresh processes against the exact shipped list; warm-up blocks title display; checks run outside the App. Repackaging keeps the App directory; verified digests/data seals are reused. Installed-App recognition, build routing, --plan, host-only update and shared recorded/default work-folder selection are connected. Full builds can reuse a nonempty work root without deleting its earlier artifacts. Behavioral tests cover publication, digest reuse/invalidation, exact-list/corruption rejection, Launcher/update decisions and work-root retention.
  4. iPad tools: codec sources and CMake/Ninja are pinned through tools/deps; XcodeGen is obtained through the same helper. Both codec archives were cross-built with PATH limited to /usr/bin:/bin:/usr/sbin:/sbin. A complete new iPad app/device run is still unverified and documented as such.
  5. Notices and Mac rerun: corrected SPIRV-Cross path/revision and packaged dependency notices. The revised Mac host rendered both Chinese scripts; language changes persisted across restart/runtime update, and chapter 1 accepted movement/attacks. Muted gameplay samples were around 60 and 120 FPS at the respective targets; 120 remains experimental. The earlier encode-drain abort did not recur, but this is bounded evidence rather than proof that its full root cause is resolved. Original saves/account hashes were unchanged.

Local checks: 61 TMNT tests, 7 packaging-standard checks, 3 no-Homebrew checks, 7 work-folder checks and 10 dependency-helper checks passed, alongside selected Launcher/collector checks. The complete container build succeeded from the original NSP/keys in a nonempty work root, with fresh extraction/rewrites. A fresh-directory integration failure exposed missing NRO staging before the external link check; that ordering is fixed and regression-covered. The actual express update also passed; App inode, game hash and all signed shader-bundle bytes were preserved, and deep/strict signature verification passed. A post-launch check additionally caught the RomFS verification stamp being written inside the App; the launcher now routes it to the external profile, with a launcher regression that checks the App stays untouched. The final muted startup/exit was then repeated, and deep/strict signature verification passed afterward.

Maintainer coordination still needed: please register tmnt in the separate website inbox and confirm its endpoint. This checkout now records/collects only under the TMNT ID, and uploads remain disabled pending that registration. The website repository returned 404 for this contributor; no server-side support or successful upload is claimed.

Add the native host, graphics and audio integration, verified base-game build entry, shared pinned dependencies, source provenance, and Simplified and Traditional Chinese support.
@HaomingJu
HaomingJu marked this pull request as ready for review November 16, 2026 07:55
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.

2 participants