ORIX Arcade — implementation plan
Written 2026-11-21 after the Phase 0 audit. Progress against it is tracked in docs/PROGRESS.md.
Audit findings
| Item | Finding |
|---|---|
| Repository | None existed. Created at ~/Desktop/Cluster/apple/ORIXArcade (git, branch main). |
| Toolchain | Xcode 27.2 (27B52), XcodeGen, simulator runtime iOS 26.5 only. |
| Devices | Simulators only; no physical iPhone attached. Dedicated simulator "ORIXArcade iPhone" (iPhone 17 Pro). |
| Signing | Team 3YM54G49SN, automatic signing with the team App Store Connect API key already on this Mac. |
| Reusable | Release recipe of the ORIX family (archive, export, altool). No shared game code. |
| Assets | None. Decision: all art, sound and music are generated in code — nothing to license. |
Architecture
text
App/ entry point, root navigation, lobby, awards, settings
DesignSystem/ tokens (colour, type, spacing, motion), components, backgrounds, logo
ArcadeCore/ game catalogue + descriptor contract, services, seeded RNG, SpriteKit base scene, in-game chrome
AudioHaptics/ procedural synth, audio director, Core Haptics director
Persistence/ versioned Codable save, store with backup / recovery / export / import
Games/<Game>/ one folder per game: pure rules, SpriteKit scene, SwiftUI screens, save model
Tests/ unit tests (XCTest, hosted in the app)
UITests/ UI smoke testsDecisions:
- One app target, no packages. Three games and a small core do not justify package overhead; folders give the boundaries.
- Swift 6, main-actor by default in the app target; pure data types are
nonisolated. - Each game owns its flow (menu → play → results) behind a
GameDescriptor; the lobby knows nothing else about it. - Rules are pure Swift, separate from SpriteKit rendering, so scoring, generation and traffic logic are unit-tested deterministically.
- Codable JSON save rather than SwiftData: one small document, trivial export/import, explicit migration hook, corruption fallback to a rolling backup. Unreadable files are set aside, never deleted.
- Procedural audio (AVAudioEngine, buffers rendered at launch) on an
.ambientsession: obeys the silent switch, mixes with the player's music. - Automatic effect scaling:
ArcadeScenelowers particle counts when frames run long or Low Power Mode is on. - iPhone only, portrait only, iOS 18+, dark-only art direction.
Milestones and acceptance criteria
| # | Milestone | Accepted when |
|---|---|---|
| 1 | Foundation: project, design system, persistence, audio/haptics, game host, lobby | Builds; lobby, awards and settings run on the simulator; persistence tests pass |
| 2 | Traffic Mayhem | 3 layouts, tutorial, fair spawner proven by seeded simulation tests, scores saved |
| 3 | Domino City | 15 levels each cleared by its reference solution, stars and unlocks saved |
| 4 | Dig to Core | 4 biomes, 10 upgrades, seeded generation with traversability tests, economy saved |
| 5 | Integration and polish | All three reachable from the lobby, pause/resume, achievements, settings honoured |
| 6 | Proof | Unit + UI tests run; real screenshots captured and inspected; metrics recorded with environment |
| 7 | Release | Archive signed, uploaded to TestFlight, repository pushed, README and report written |
The three games are developed in parallel in separate git worktrees on top of milestone 1 and merged for milestone 5.
Risks
| Risk | Mitigation |
|---|---|
| SpriteKit physics is not bit-exact, so domino outcomes could vary | Fixed setups, capped bodies, wide solution tolerances, reference solutions replayed by a bot |
| Unfair traffic spawns | Spawner consults the conflict table and reaction-time budget; long seeded simulations in tests |
| Procedural terrain producing dead ends | Carved guaranteed route per chunk, validated in tests over many seeds |
| No physical device | Simulator verification only; device feel, haptics and real frame rates are reported as not measured |
| Simulator frame times are not device frame times | Metrics are labelled with their environment and never presented as device results |