duo-games
Builds games for iPhone Duo, Apple's foldable. The game fills the closed outer display, the open inner display, book pose and tabletop by changing its aspect ratio instead of letterboxing, as Apple's
SKILL.mdplugins/duology-features/skills/duo-games/SKILL.md
GitHubduo-games
A game on iPhone Duo resizes every time someone opens, closes, rotates or folds the phone, often in the middle of play. This skill keeps the game running through all of it, fills every pose, keeps thumbs off the fold, and turns the bottom half into a controller when the phone sits on a table.
Load neighbours when the task needs them: duo-shared-screen and recipe-two-player-game (two people on one phone), duo-postures (every pose, and hinge effects), duo-layout (reserved regions in depth), duo-continuity (state through a fold), duo-ergonomics (thumb reach).
"Book" and "tabletop" are Duology's words for Apple's "partially folded, like a book" and "seated on a table like a laptop". No API reports them. Labels: measured means we ran it in a probe app on the iPhone Duo simulator (Xcode 27.1, iOS 27.1, 20 Oct 2026); logs in references/measurements.md. Unverified means we could not confirm it. Everything else links to Apple.
Rules
- Fill the screen in every pose. Change the aspect ratio: show more or less of the world. Letterbox only when you can't avoid it, and then put artwork in the bars (HIG: iPhone Duo).
- Keep text and controls the same size in every pose. Size them in points, outside the world, not in world units that a camera scales (HIG: iPhone Duo).
- One game per window, owned above every layout switch. A fold resizes the scene or the drawable. It never makes a new scene, renderer or game state.
- Resize, don't restart. Size callbacks only recompute what depends on size: the camera, the projection, size-matched textures.
- Nothing touchable in the fold. Movement on the leading side, actions on the trailing side, and the whole
.divisionframe, margins included, belongs to neither, flat or folded (talk 111466). - Tabletop: the world in the top region, the controls in the bottom region, and the same controls as every other pose. Apple suggests this split for media on a table; it fits games too (talk 111466).
- Handle tall and wide in every build. You may lock the orientation, but the inner display ignores the lock (talk 111461).
- Touch always works. A game controller is an extra. Hide touch controls only after the player uses a controller (HIG: Game controls).
- Pause on the scene phase, never on a fold. Folding is part of play. Set the scene's own
isPaused:SpriteView(isPaused:)didn't resume the game (measured). - No hinge as a game input unless the player turns it on and an on-screen control does the same job (
duo-postures).
What the game gets in each pose
Measured with the code below: the world ignores the safe area, the controls stay inside it.
| Pose | Window | Scene (world) | Touch controls | .division seen by the controls |
|---|---|---|---|---|
| Closed | 466 × 678 pt | 466 × 678 pt | 382 × 644 pt (84 pt trailing and 34 pt bottom inset) | none |
| Open, flat, held wide | 951 × 669 pt | 951 × 669 pt | 951 × 635 pt | inactive, 40 × 669 pt at x = 455.5 |
| Book | 951 × 669 pt | 951 × 669 pt | 951 × 635 pt | active, same frame |
| Tabletop | 669 × 951 pt | 669 × 455.7 pt, above the fold | 669 × 421.5 pt, below the fold | none: the fold lies outside the controls |
- The fold's frame runs from x = 455.5 to 495.5. That is centred in a full-width 951 pt game, but not in a view that a vertical bar narrows: in an 867 pt view the middle is 22 pt left of the fold (measured in
duo-reading). Split at the fold frame, never atwidth / 2. - Open, held tall, and Split View were not measured with this game. Plan for any size.
1. Fill the screen: resize the scene, move the camera
.resizeFill makes the scene exactly the size of its view (resizeFill). A camera then scales so the play area always fits; spare room shows more world. Every pose we measured is less wide than the 16:10 play area below, so it fills the width and the spare room shows above and below it: a lot on the closed phone held upright, little in book and tabletop (derived from the measured sizes).
import SpriteKit
/// What the touch controls and a game controller write, and the scene reads every frame.
@MainActor
final class GameInput {
var move = CGVector.zero // -1...1 on each axis
var isFiring = false
}
/// The game world. `.resizeFill` makes the scene exactly the size of its view, so a
/// fold, a rotation or Split View changes the aspect ratio instead of letterboxing.
/// The camera keeps the whole play area in view; spare room shows more world.
final class ArenaScene: SKScene {
/// The part of the world every size must show, in world points.
let playArea = CGSize(width: 640, height: 400)
let input: GameInput
private let eye = SKCameraNode()
init(input: GameInput) {
self.input = input
super.init(size: playArea)
scaleMode = .resizeFill
}
required init?(coder: NSCoder) { nil }
override func didMove(to view: SKView) {
guard camera == nil else { return } // can run again; build the world once
addChild(eye)
camera = eye
// Add the world's nodes here, around (0, 0).
}
/// Runs on every fold, unfold, rotation and Split View change. Never rebuild the world here.
override func didChangeSize(_ oldSize: CGSize) {
super.didChangeSize(oldSize)
guard size.width > 0, size.height > 0 else { return }
// Scale so the play area fits on both axes. Never crop it.
eye.setScale(max(playArea.width / size.width, playArea.height / size.height))
}
override func update(_ currentTime: TimeInterval) {
// Read `input` here: it keeps its values through a resize.
}
}
- Draw the world beyond the play area, in every direction. A view wider than the play area's shape (Split View, or a different play area) shows the extra at the sides instead.
- Put the score, menus and labels in SwiftUI over the scene, in points. A camera scale would make them grow and shrink with each fold.
- Keep
didChangeSize(_:)cheap and safe to repeat. Measured: it ran twice for every size change, and once with a passing size (466 × 455.7 pt) when the phone closed from tabletop. - Can't change the aspect ratio? Letterbox with artwork in the bars. Code: references/scene-and-renderer.md.
2. One game through every fold
Create the session once per window, above every layout switch. The same SpriteView and scene stay on screen in every pose; only their size changes.
import Observation
import SpriteKit
import SwiftUI
// requires: FoldGeometry (references/fold-geometry.md)
// requires: GameInput, ArenaScene (SKILL.md)
// requires: GameLayout (references/tabletop-controller.md), TouchControls (references/touch-controls.md)
// requires: ControllerAware (references/controllers.md)
/// One game per window. Create it in the window's root view, above every layout
/// switch, so a fold never makes a new scene.
@MainActor @Observable
final class GameSession {
let input = GameInput()
let scene: ArenaScene
var isPaused = false
init() { scene = ArenaScene(input: input) }
}
@available(iOS 27.1, *)
struct GameScreen: View {
let session: GameSession
@State private var fold = FoldGeometry()
@Environment(\.scenePhase) private var phase
var body: some View {
GameLayout(fold: fold) {
// The same SpriteView and scene in every pose: only its size changes.
SpriteView(scene: session.scene, preferredFramesPerSecond: 120)
.ignoresSafeArea()
ControllerAware(input: session.input) {
TouchControls(input: session.input) // hidden while a controller is in use
}
}
.onFoldChange { fold = $0 }
// Pause the scene itself. SpriteView's isPaused argument paused the scene
// but didn't resume it when it turned false again (measured).
.onChange(of: session.isPaused || phase != .active, initial: true) { _, paused in
session.scene.isPaused = paused
}
.background(.black)
.toolbarVisibility(.hidden, for: .statusBar)
.persistentSystemOverlays(.hidden)
}
}
- Measured: one scene object from launch to the end of the run, through closed, open, book, tabletop and closed again.
didMove(to:)ran once, and the frame counter kept counting through every change. - Pause only when
scenePhaseleaves.active. Opening or closing the phone kept the app active (measured: frames kept counting), so a fold never pauses the game. - Pause the scene, not the
SpriteView. Measured: withSpriteView(isPaused:)bound to the phase, a game launched while the app was still inactive stayed frozen once it became active (0 frames in 4 s), and so did a pause button turned off again: the argument set the scene'sisPausedbut didn't clear it. Settingscene.isPausedinonChangeran in every case, and again after a trip to the Home Screen. .ignoresSafeArea()on the world only. Controls, score and menus stay in the safe area, clear of the outer camera and the Home indicator (HIG: Game controls).persistentSystemOverlays(.hidden)andtoolbarVisibility(.hidden, for: .statusBar)during play only. Show them again on menus (persistentSystemOverlays(_:),toolbarVisibility(_:for:)). The.statusBarplacement is new in iOS 27.0; the iOS 27.1 SDK marksstatusBarHidden(_:)to be deprecated in its favour. Deploying below iOS 27 (the recipes target iOS 26.0),.statusBardoesn't build without a check (measured), so keep the old call for older versions:
import SwiftUI
extension View {
/// Hides the status bar: the `.statusBar` placement on iOS 27, statusBarHidden() before.
@ViewBuilder func playStatusBarHidden() -> some View {
if #available(iOS 27.0, *) {
toolbarVisibility(.hidden, for: .statusBar)
} else {
statusBarHidden()
}
}
}
3. Touch controls off the fold
Movement goes on the leading side and actions on the trailing side, as players expect (HIG: Game controls). On the inner display held wide, that line is the fold. TouchZones puts the fold's whole frame between the zones, flat or folded, so folding moves nothing.
import SwiftUI
// requires: FoldGeometry (references/fold-geometry.md)
/// Movement on the leading side of the fold, actions on the trailing side.
/// Without a top-to-bottom fold the line is the middle. The fold's frame, margins
/// included, belongs to neither zone, flat or folded, so folding moves nothing.
@available(iOS 27.1, *)
nonisolated struct TouchZones: Equatable, Sendable {
var move: CGRect
var act: CGRect
init(size: CGSize, fold: FoldGeometry) {
let gap = fold.isVertical ? fold.frame : nil
let lead = gap?.minX ?? size.width / 2
let trail = gap?.maxX ?? size.width / 2
move = CGRect(x: 0, y: 0, width: lead, height: size.height)
act = CGRect(x: trail, y: 0, width: size.width - trail, height: size.height)
}
}
- Measured in book: movement 0 to 455.5 pt, actions 495.5 to 951 pt. Closed, the line is the middle of the 382 pt control area; in tabletop, the middle of the bottom region.
- Measured by UI test: in book, a drag from x = 445 pt moved the stick and a drag from the fold's centre did nothing; fire and the stick worked closed, in book and in tabletop.
- Show the stick where the thumb lands, not at a fixed spot. Buttons at least 44 × 44 pt, with a pressed look, a haptic and a symbol that says what they do (HIG: Game controls).
- Read the fold in the controls' own view. Frames are in that view's space (
ReservedRegion). - Measured: the first layout pass reported no fold. The zones then split at the middle for one pass. React to changes; don't read once.
TouchControls (stick and fire button) and PressButton, plus Apple's GCVirtualController and Touch Controller on iPhone Duo: references/touch-controls.md.
4. Tabletop: the bottom half is the controller
Propped on a table, the phone becomes a small console: the world in the top region, every control in the bottom region. In every other pose the controls lie over the world. One Layout does both, so neither view is rebuilt (talk 111463).
- Measured: tabletop gave the scene 669 × 455.7 pt above the fold and the controls 669 × 421.5 pt below it.
- Without this layout, the play area crossed the fold in tabletop (measured with
GCVirtualControllerover a full-window scene). - The inner camera sits on the right edge of the bottom region (
duo-postures). It is inactive unless your game runs it. Keep the fire button clear of it anyway. - Held tall and flat (no active fold), the layout keeps the overlay.
GameLayout and its variants: references/tabletop-controller.md.
5. Metal and UIKit
MTKViewresizes its drawable with the view by default (autoResizeDrawable). Rebuild the projection inmtkView(_:drawableSizeWillChange:). Keep the device, queue, pipelines and game state.- Measured: the drawable went from 1398 × 2034 px closed to 2853 × 2007 px open and 2007 × 2853 px in tabletop. Folding into book didn't call it: the size didn't change.
- UIKit loop: get the display link from
UIWindowScene.displayLink(target:selector:)(iOS 27). Apple's doc says it follows the scene when the scene moves to another display, as it does when the phone opens or closes (doc).UIScreen's display link is deprecated in iOS 27.
Code for MTKView, a CAMetalLayer view controller and Touch Controller: references/scene-and-renderer.md.
6. Game controllers
ControllerAware shows the touch controls until the player uses a controller, then hides them, and brings them back on the next touch. Code: references/controllers.md.
- Measured: the iPhone Duo simulator reported a connected controller named "Gamepad" (product category MFi, not attached to the device) shortly after every launch, with no controller on the Mac. A game that hides touch controls as soon as a controller connects would hide them on every simulator run. Wait for input.
- Measured:
GCVirtualControllerdrew its stick bottom left and its buttons bottom right in book, clear of the fold. In tabletop its buttons sat below the fold. It doesn't know about the fold; check it in every pose. - Measured:
TCTouchController.isSupportedwasfalseon the simulator. Test Apple's Touch Controller on a device.
7. Orientation locks
The outer display honours your supported orientations; the inner display doesn't (talk 111461). Apple lets games lock to portrait or landscape, as long as they fill the screen as the pose changes (HIG: iPhone Duo).
- Measured with a landscape-only build: on the closed phone held upright the game ran sideways (678 × 466 pt), as on any iPhone. In tabletop it got a tall 669 × 951 pt window, lock or not.
- So build every screen for both shapes, even with a lock. The play area and
GameLayoutabove already do. - Never read
UIDevice.orientationor the interface orientation to choose a layout. Use the view's size.
What a landscape-only build got in each pose: references/measurements.md.
8. Two players on one phone
Use the two-player frame, not this skill's controls:
recipe-two-player-gamecreates a new project: one half per player in every pose, an engine tested on the Mac, and UI tests for the Duo simulator.duo-shared-screenadds the same to an existing game:SharedSplit, face-to-face seating, input gated per seat.- Not
ArrangementView: closed and held sideways it shows only its first view (measured induo-layout). - Two controllers: give each player one, by
playerIndex, and keep touch for both. references/controllers.md.
Frame rate, system gestures and haptics
- Ask for 120 frames per second (
preferredFramesPerSecond), and addCADisableMinimumFrameDurationOnPhoneto Info.plist, or iPhone stays at 60 (ProMotion guide). The simulator ran at 60 (measured: 300 frames every 5 s). Check 120 Hz on a device. - Controls near an edge:
defersSystemGestures(on:)during play, so a swipe that starts at that edge reaches the game before the system (doc). - Haptics shake the whole phone. Keep them short, and offer a switch (HIG: Playing haptics).
Test it
In Device Hub, under the bezel: Closed, Open, Partially Open, and Rotate Right for tabletop (Device Hub).
- Start a round closed. Open, fold, rotate into tabletop and close while it plays. The round never restarts, and the score and positions stay.
- Book: no stick, button or menu inside the fold frame (455.5 to 495.5 pt held wide).
- Tabletop: the world above the fold, every control below it.
- Every pose: the whole play area shows; nothing is cut off and no plain black bars appear.
- Controller: touch controls stay visible until you press a button, and come back on touch. On the simulator, expect the "Gamepad" controller to be connected already.
- Split View on the inner display, on both sides: the game fills its half.
- Screenshots:
xcrun simctl io <UDID> screenshot --display=primary outer.png(closed) and--display=primary-1 inner.png(open).
Checklist
- The scene uses
.resizeFill(or the renderer follows the drawable size); nothing letterboxes without artwork. - A camera or projection keeps the whole play area visible at every aspect ratio.
- Score, menus and touch controls are sized in points, outside the world, and keep their size in every pose.
- One session, scene and renderer per window, created above the layout; nothing is rebuilt on a fold.
- Size callbacks are cheap, repeatable and never reset game state.
- Touch zones split at the
.divisionframe read with.includeInactive; no control inside it, flat or folded. - Tabletop: the world above the fold, the same controls below it.
- The game pauses on
scenePhaseby setting the scene'sisPaused, never on a fold. - Touch controls stay until a controller is used, and come back on touch.
- The game works tall and wide on the inner display, whatever orientation it locks.
- Two players use
recipe-two-player-gameorduo-shared-screen, notArrangementView. - iOS 27.1 APIs are behind
@availableorif #availablewhen the game deploys lower. - Checked in Device Hub: Closed (portrait and landscape), Open (wide and tall), book, tabletop, Split View.