SPB Git

Repository Public License

IMPLEMENTATION_PLAN.md 4.2 KB

# 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 tests

Decisions:

  • 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 .ambient session: obeys the silent switch, mixes with the player's music.
  • Automatic effect scaling: ArcadeScene lowers 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
Files main
Menu

Theme