Dimillian/PokeSwift: Native macOS Pokémon Red in Swift

Dimillian/PokeSwift: Native macOS Pokémon Red in Swift

Developers interested in game engine reimplementation, Swift on macOS, or the technical archaeology of classic Game Boy titles face a common challenge: how to preserve original game logic while building modern, native experiences. Most approaches either wrap emulators in thin UI layers or require runtime parsing of archaic assembly formats. Neither delivers the performance, testability, or maintainability that native development promises.

Dimillian/PokeSwift takes a different path. It is a native macOS reinterpretation of Pokémon Red built in Swift and SwiftUI, with a deterministic extraction pipeline that transforms the canonical pret/pokered disassembly into runtime content without parsing .asm files at launch. This article breaks down how the project works, what it ships today, and how developers can build and extend it.

What is Dimillian/PokeSwift?

Dimillian/PokeSwift is an open-source project maintained by Thomas Ricouard that reimplements the Pokémon Red/Blue engine as a native macOS application. The repository sits at 351 GitHub stars and 37 forks as of its last commit on March 19, 2026, with Assembly identified as the primary language due to its inclusion of the original pret/pokered disassembly.

The project's architecture reflects a deliberate engineering decision: rather than treating the disassembly as a runtime dependency, it uses the disassembly as a source of truth for deterministic content extraction. A Swift CLI tool reads the assembly and original assets, generates validated runtime artifacts, and the native macOS app loads those artifacts directly. This keeps the Swift runtime clean, testable, and free from assembly parsing overhead.

The project targets macOS 26.0 and later and uses Tuist for workspace management. It is not a ROM hack, emulator wrapper, or translation layer. It is a ground-up engine reimplementation with telemetry, runtime traces, and a modular architecture separating core logic (PokeCore), UI (PokeUI), content loading (PokeContent), extraction (PokeExtractCLI), and telemetry (PokeTelemetry).

Milestones M1 and M2 are complete. The app currently reaches launch -> splash -> titleAttract -> titleMenu, with full-game scope tracked in SWIFT_PORT.md.

Key Features

Deterministic Content Extraction Pipeline The PokeExtractCLI target reads the pret/pokered disassembly and writes deterministic runtime artifacts to Content/Red/. This pipeline ensures that any change in the canonical disassembly propagates through validated, reproducible build steps rather than ad-hoc manual updates.

Native Swift Engine with SwiftUI Shell The game logic lives in PokeCore as a headless runtime, while PokeUI provides reusable SwiftUI rendering components. This separation enables unit testing of game state without UI dependencies and allows the macOS app shell to evolve independently from engine internals.

Telemetry and Runtime Traces PokeTelemetry provides runtime snapshots and control surfaces for automated debugging and validation. This is particularly valuable for a reimplementation project where behavioral parity with the original is a measurable goal rather than a subjective claim.

Original ROM Build Preservation The repository still builds the original Game Boy ROM targets—Pokémon Red (UE), Pokémon Blue (UE), BLUEMONS.GB debug build, and two patch files—with verified SHA-1 hashes. This preserves the historical toolchain and provides a ground-truth comparison for the Swift reimplementation.

Supplemental Asset Integration Bag UI item sprites come from the msikma/pokesprite project, vendored under ThirdParty/PokeSprite/ and subset-copied into generated runtime content. The extractor handles reference tracking so only used sprites ship.

Tuist-Managed Workspace The build system uses Tuist to generate the Xcode workspace, making the project structure declarative and reproducible across developer machines.

Use Cases

Game Engine Reimplementation Research Developers studying how to port classic assembly-based games to modern languages can use Dimillian/PokeSwift as a reference architecture. The extraction pipeline pattern—canonical disassembly → deterministic artifacts → native runtime—is applicable beyond Pokémon to any project with preserved assembly sources.

Swift on macOS Game Development Teams evaluating Swift and SwiftUI for non-trivial interactive applications get a working example of state management, rendering pipelines, and content loading at game-scale complexity. The modular target structure (PokeCore, PokeUI, PokeContent) demonstrates production-grade separation of concerns.

Retro Game Preservation Engineering Preservationists and technical historians can examine how the project maintains fidelity to original ROM behavior while building a native experience. The committed SHA-1 hashes, original toolchain documentation in docs/INSTALL.md, and living port ledger in SWIFT_PORT.md provide auditability that wrapper-based approaches lack.

Telemetry-First Debugging Patterns The PokeTelemetry subsystem offers a model for projects where automated validation matters. Runtime traces and snapshots enable regression detection without manual playtesting—critical for any reimplementation claiming behavioral parity.

Tuist and Modern Xcode Workflow Adoption Teams standardizing on Tuist for workspace generation can study a real-world application with multiple targets, CLI tools, and generated content pipelines.

Installation & Setup

The project provides three primary shell scripts for building and running. Reproduce these exactly:

# Generate Tuist workspace, build Swift targets
./scripts/build_app.sh

# Extract and verify Red runtime content from disassembly
./scripts/extract_red.sh

# Launch the native macOS app
./scripts/launch_app.sh

For normal app usage after initial setup, ./scripts/launch_app.sh alone is sufficient.

Step-by-step breakdown:

1. Clone the repository including submodules if the disassembly is referenced as such (verify with git submodule status).

2. Run ./scripts/build_app.sh — This invokes Tuist to generate the .xcodeproj/.xcworkspace, then builds all Swift targets. Ensure you have Tuist installed and macOS 26.0 SDK available.

3. Run ./scripts/extract_red.sh — This executes PokeExtractCLI against the pret/pokered disassembly in the repository, writing deterministic artifacts to Content/Red/. The script includes verification steps; extraction failures will block subsequent app launches.

4. Run ./scripts/launch_app.sh — This launches the built macOS app. The app loads extracted content from Content/Red/ and initializes through launch -> splash -> titleAttract -> titleMenu.

Prerequisites: macOS 26.0 or later, Xcode with Swift 6.x toolchain, Tuist CLI, and sufficient disk space for the disassembly and extracted artifacts.

Real Code Examples

The README does not contain extensive inline code samples. What follows are the documented commands and architectural patterns, presented with context. The limited code surface in the documentation reflects the project's current stage—engine implementation with user-facing API stabilization still in progress.

Build and extraction orchestration:

# Primary developer commands (from README)
./scripts/build_app.sh    # Tuist generate + Swift build
./scripts/extract_red.sh  # Deterministic content extraction
./scripts/launch_app.sh   # App launch

These scripts encapsulate what would otherwise be multi-step Tuist and Xcode operations. The extraction step is non-optional: the app does not parse .asm at runtime, so stale or missing Content/Red/ artifacts will cause launch failures.

Project target structure (documented layout):

App/                      # Native macOS app host
Sources/PokeCore/         # Headless game/runtime state
Sources/PokeUI/           # Reusable SwiftUI rendering and scene components
Sources/PokeContent/      # Runtime content loading and validation
Sources/PokeExtractCLI/   # Deterministic extraction from disassembly
Sources/PokeTelemetry/    # Runtime snapshots and control surfaces
Content/Red/              # Extracted runtime artifacts used by the app

This structure enforces dependency direction: PokeCore has no UI dependency; PokeUI depends on PokeCore; PokeContent depends on extracted artifacts; PokeExtractCLI is a build-time tool; PokeTelemetry cross-cuts for debugging support.

Content loading architecture (described behavior):

// Conceptual flow based on README description:
// 1. PokeExtractCLI reads pret/pokered disassembly
// 2. Writes deterministic artifacts to Content/Red/
// 3. Native app loads those artifacts at runtime
//
// The Swift runtime does NOT parse .asm files directly.

This architectural constraint is intentional. Runtime .asm parsing would introduce complexity, error surfaces, and performance overhead. The extraction pipeline moves that cost to build time, where failures are catchable and deterministic.

Advanced Usage & Best Practices

Track SWIFT_PORT.md for scope decisions. This living document tracks milestones, subsystem status, parity goals, and telemetry requirements. Before contributing or extending, review it to understand what "done" means for each subsystem.

Treat Content/Red/ as generated, not source. The directory contains committed extracted artifacts for convenience, but the canonical source remains the disassembly. Regenerate via ./scripts/extract_red.sh after any disassembly update to avoid drift.

Use telemetry for parity validation. The PokeTelemetry runtime traces are designed for automated comparison against original ROM behavior. Consider integrating snapshot tests that compare telemetry output against known-good traces from the Game Boy version.

Respect the dual build system. The repository builds both Swift macOS targets and original Game Boy ROMs. Changes to the disassembly or extraction logic may affect both paths; verify ROM builds with docs/INSTALL.md when modifying shared source.

Extend PokeUI for new scenes. The SwiftUI component library is designed for reuse. New game screens should compose from PokeUI primitives rather than creating one-off views, maintaining consistency with the existing titleAttract and titleMenu implementations.

Comparison with Alternatives

Trade-offs to consider:

• Dimillian/PokeSwift sacrifices immediate cross-platform availability for native macOS performance and maintainability. It is not an emulator and will not run original ROMs.
• Upstream pret/pokered remains the authoritative source for accuracy and historical preservation, but offers no modern native experience.
• Emulation approaches run original software unmodified but carry interpreter overhead, less testable architecture, and typically non-native UI integration.

For developers prioritizing native Swift development, macOS integration, and clean separation between canonical content and runtime implementation, Dimillian/PokeSwift occupies a distinct position.

FAQ

What license covers Dimillian/PokeSwift? The repository does not specify a license. Treat usage and distribution permissions as undefined until a LICENSE file is added.

Can I run this on Windows or Linux? No. The Swift app targets macOS 26.0 and later. The original ROM build toolchain may work elsewhere, but the native app is macOS-only.

Does it play the full Pokémon Red game? Not yet. Milestones M1 and M2 are complete, reaching titleMenu. Full-game scope is tracked in SWIFT_PORT.md.

Do I need the original Pokémon Red ROM? No. The repository includes the pret/pokered disassembly as canonical source. Extraction generates runtime content from this disassembly.

How does telemetry help development? Runtime traces and snapshots enable automated debugging and validation against original behavior, reducing reliance on manual playtesting for regression detection.

Can I contribute to the Swift port? Review SWIFT_PORT.md for milestone status and next steps. The modular target structure supports parallel work on PokeCore, PokeUI, and PokeContent.

Why Assembly as the primary GitHub language? The repository includes the full pret/pokered disassembly. Swift source exists but is outweighed by assembly line count in GitHub's language detection.

Conclusion

Dimillian/PokeSwift represents a methodical, engineering-first approach to classic game reimplementation. It does not promise instant gratification or a finished product. What it offers is a clean architectural pattern—canonical disassembly, deterministic extraction, native runtime—that other preservation and reimplementation projects can adapt.

The project suits developers interested in Swift game development, technical game preservation, or the specific challenge of bridging assembly-era software to modern native platforms. It demands macOS 26.0, patience for a work-in-progress codebase, and willingness to engage with the engineering ledger in SWIFT_PORT.md.

If that matches your interests, clone the repository, run the build scripts, and examine how the extraction pipeline keeps historical accuracy and modern implementation in balance.

Start with Dimillian/PokeSwift: https://github.com/Dimillian/PokeSwift

For related reading on Swift game development patterns, see [INTERNAL_LINK: swift-game-engine-architecture].