Twinframe

iOS Nintendo DS emulator for games you already own
Interpreter-only · Metal dual-screen · Built without JIT for App Store–safe constraints

Early playable source release — not on the App Store yet.

Twinframe runs Nintendo DS software from your legally obtained .nds and .srl files. It does not ship games, BIOS, firmware, downloads, or a game catalog.

Getting started

1. Install from source — see Building from source below. There is no App Store build at this time.
2. Import a game — open Twinframe, tap Import, and choose a .nds or .srl file you already own.
3. Play — use the touch screen and on-screen controls; optional ARM9/ARM7 BIOS and firmware can be imported in Settings if you choose to supply them.

Games are never bundled with Twinframe.

Features

Play

• Stacked portrait layout with a full-width display deck, plus an optional touch-focus mode for stylus-first titles.
• Landscape side-by-side and single-screen display modes.
• Both DS screens presented through Metal on device hardware.

Controls

• Touch-screen input, D-pad, A/B/X/Y, L/R, Start/Select.
• Pause menu, hold buttons, haptics, per-game touch-control presets.
• Bundled Twinframe-authored control skins and external controller support.

Saves and session

• Battery saves and backup history.
• Save-state browser with thumbnails, in-app screenshots, fast-forward, pause/resume, and return to library.

System

• Optional user-imported DS ARM9 BIOS, ARM7 BIOS, and firmware (FreeBIOS/generated firmware fallback when disabled).
• Audio through public iOS APIs.
• On-screen FPS counter and local-only performance telemetry (data stays on your device).

Requirements

OS	iOS 26
Recommended	iPhone 15 and newer (primary layout and performance target)
Best-effort	iPhone 14 family — controls and layout should remain reachable without clipping
iPad	Installable; not optimized

Project status

What works today: booting user-imported DS software through a melonDS-backed core, dual-screen Metal presentation, touch and controller input, audio, battery saves, save states, and the normal in-app library flow.

What is not ready: App Store distribution. Release is blocked until GPL source packaging, third-party notices, provenance for local core patches, and App Store preflight are complete. See Docs/LICENSE_GATE.md.

How we test: the project builds on the iOS Simulator for general validation. Real-device validation (Metal upload paths, thermal behavior, and performance claims) requires a physical iPhone — the Simulator does not represent shipping graphics behavior.

What Twinframe does not include

• Bundled ROMs, games, BIOS, firmware, keys, or other copyrighted console assets.
• Game download catalogs, scraping, stores, or cloud ROM services.
• JIT, dynamic code generation, executable-memory toggles, or private Apple APIs.
• DSi mode, Wi-Fi/WFC, netplay, or camera support in v1.
• Native iOS APIs exposed to emulated software.
• Third-party skin downloads, remote skin catalogs, or user-imported skin packages.

Building from source

Clone with submodules (melonDS lives under Vendor/melonDS):

git clone --recurse-submodules https://github.com/PowerBeef/twinframe.git
cd twinframe

Generate the Xcode project, build the iOS core, and build the app:

xcodegen generate
Scripts/build_melonds_ios.sh
xcodebuild -project Twinframe.xcodeproj -scheme Twinframe \
  -destination 'platform=iOS Simulator,name=iPhone 17 Pro,OS=26.5' \
  CODE_SIGNING_ALLOWED=NO build

Device builds and on-device testing need a signing team and a physical destination, for example:

export DEVELOPMENT_TEAM=<your-team-id>
xcodebuild -project Twinframe.xcodeproj -scheme Twinframe \
  -destination 'platform=iOS,id=<device-udid>' \
  -allowProvisioningUpdates build

Release and compliance checks

Run before any archive or distribution work:

xcodebuild -project Twinframe.xcodeproj -scheme Twinframe -configuration Release \
  -destination 'generic/platform=iOS' CODE_SIGNING_ALLOWED=NO build
xcodebuild -project Twinframe.xcodeproj -scheme Twinframe -configuration Release \
  -destination 'platform=iOS Simulator,name=iPhone 17 Pro,OS=26.5' build
Scripts/app_store_preflight.sh /path/to/Twinframe.app
Scripts/verify_melonds_archives.sh
Scripts/prepare_release_tag.sh

Do not commit ROMs, saves, BIOS files, firmware, screenshots from commercial games, or local test artifacts.

Core direction

Twinframe starts from upstream melonDS 1.1, pinned under Vendor/melonDS, as the baseline for an iOS-only fork. Optimization work targets iOS 26, arm64, A15+ devices, Metal presentation, AVAudio, app lifecycle, and sandboxed file I/O — without desktop frontend portability or JIT.

Documentation

• THIRD_PARTY_NOTICES.md
• Docs/PROVENANCE.md
• Docs/LICENSE_GATE.md
• Docs/PERFORMANCE_OPTIMIZATION.md

Legal and licensing

Twinframe is distributed as public source under GPL-3.0-or-later to stay compatible with melonDS. Local iOS-only melonDS fork patches must remain documented with corresponding source availability and reproducible build instructions.

Twinframe is not affiliated with, endorsed by, or sponsored by Nintendo. Nintendo DS is a trademark of Nintendo. You are responsible for providing legally obtained game files and complying with applicable law.

Do not prepare App Store release artifacts until Docs/LICENSE_GATE.md, Docs/PROVENANCE.md, and THIRD_PARTY_NOTICES.md are accurate for the exact source tree you ship.