Mobile touch controls survey

Mobile touch controls research: Dark Cosmos on iPhone / iPad

Current scheme summary

Dark Cosmos (Bullet Heaven) currently uses a floating left-side virtual joystick for movement, combined with a fixed bottom-right aim stick and fanned ability buttons. Implementation details:

Movement: Floating joystick in left half of screen (touches left of JOY_ZONE_FRAC * screen_width), JOY_RADIUS=90px, JOY_DEADZONE=0.12
Aiming: Fixed aim stick, bottom-right at (screen.x - MARGIN - AIM_RADIUS, screen.y - MARGIN - AIM_RADIUS), AIM_RADIUS=60px, AIM_ACTIVATE_R=140px
Abilities: Two buttons (WARP/DRONE) fanned around aim stick on an arc (FAN_RADIUS=110px, ABILITIES data-driven), each showing charge/ready state via animated arcs
Drone tap-vs-hold: Tap deploys (under DRONE_HOLD_MS=400ms), hold opens Drone Bay
Pause/HUD toggle: Small buttons top-right (PAUSE_R=19px)

File refs: ui/touch_controls.gd (lines 14-33 tunable consts, inner _Pad class handles input), input/input_router.gd (lines 174-225 touch event handling, lines 312-340 touch decoy/dash logic).

Visibility and tutorial gating: Controls hidden on tvOS/desktop (controlled by Platform.is_touch()). Ability locks (lines 101-111 in touch_controls.gd) gate tutorial progression by visibility—locked abilities are neither drawn nor hit-tested. Tutorial stage-gating (2026-08-10 redesign) defeated on iOS because this layer’s visibility bypasses the tutorial condition; all controls are available immediately (this is a known gap, see CLAUDE.md “Open items”).

Research findings by topic

Twin-stick control best practices (iOS)

Joystick placement and behavior:

Movement controls on left, aiming/firing on right: matches console expectations and divides thumb zones evenly
Dynamic joystick centers at finger contact point (not fitted to screen edges), removing camera shudder and unintended movement
Keep joystick hidden when idle; show only on touch (current scheme: visible when _joy_idx != -1)
Deadzone filtering (0.1-0.15) removes jitter; current scheme uses JOY_DEADZONE=0.12 ✓

Size considerations:

Virtual joystick radius should be thumb-sized: 60-100px is standard (current: 90px ✓)
Ability buttons: 44pt (Apple HIG minimum) is ~52px; current WARP/DRONE are BTN_R * 2/3 ~= 39px, below Apple’s accessibility minimum
Pause button is 38px diameter—also below 44pt minimum

iPad-specific issues:

Thumbs on iPad don’t reach the center of the screen; buttons placed bottom-right work if below the comfortable thumb arc
Fixed aim stick at bottom-right is correctly positioned for two-handed grip
Current MARGIN=46px should account for Dynamic Island and system home indicator on notched iPhones ✓

Gesture-based ability triggers

Swipe-to-dash evaluation: The idea of sliding the right thumb from the aim stick area to trigger warp (dash) and drone (decoy) introduces several risks:

Conflict with aim stick: Right-thumb drag is already committed to aiming. A secondary swipe gesture in the same zone requires disambiguating intent (is this a fast aim drag, or a swipe?). Requires velocity/distance threshold tuning.
Accidental triggers: High velocity aim corrections (quick swipe to flick-aim) would frequently fire dash unintentionally.
Inconsistent with Brawl Stars pattern: Brawl Stars reserves swipe for directional aim release, not ability trigger; abilities use separate buttons (tap for auto, drag to aim/release).
Precedent from Dead Cells: Dead Cells offers swipe-to-dodge as an optional alternative to a button, not the primary mechanism. Playtests showed gestures alone were imprecise; the button stayed.

Recommendation: Do not use swipe for ability triggers on the aim thumb. Keep ability buttons as separate UI elements. A swipe pattern could work for additional mechanics (e.g., screen-edge swipe to change weapons), but not interleaved with aim.

Ability button UX patterns

Brawl Stars model (most polished example):

Right side divided into zones: attack (auto-tap or drag-to-aim), super (same dual-mode), gadget/hypercharge above
Each ability: tap for auto-fire, hold+drag to manually aim, release commits
Haptic feedback on long-range hits confirms input
Charge indicators built into button graphics (glow ring for charged, dim for cooling)
Current Dark Cosmos approximates this: charge arcs on buttons ✓, but lacks haptic feedback

Radial menu alternative (unexplored for Dark Cosmos):

Long-hold on aim stick (or separate center area) opens a radial menu
Drag to select ability, release to fire
Pros: compact, gestural feel, scales to 3+ abilities
Cons: adds 500ms delay, interrupts aiming flow (not suitable for real-time twin-stick)

Current state: Fanned buttons around aim stick is a hybrid approach—space-efficient and doesn’t interrupt aiming.

Safe area and notch handling

Apple’s 2026 guidance (Touch Controller framework):

Design for 9 anchor points (corners, edges, center—avoid center for gameplay)
Always account for Dynamic Island (iPhone 14+), home indicator, rounded corners
Safe area insets should keep touch targets 44pt+ away from screen edges
Test on both iPhone (narrow, portrait-heavy) and iPad (wide, two-handed)

Current scheme audit:

Pause/HUD buttons at top-right (24px from edge)—too close to Dynamic Island on iPhone
Aim stick anchored at MARGIN=46px—safe
Move joystick floating—no edge constraint issue
No explicit safe-area calculation in current code

iPad vs. iPhone control layout differences

iPhone (one hand + portrait optional):

Thumbs reach edges and bottom; center is unreachable
Current layout works: left thumb at left edge, right thumb at bottom-right (thumbs don’t overlap)

iPad (two hands, landscape holding both sides):

Thumbs occupy bottom corners; center screen is reachable but hands block it
Bottom-right aim stick requires right thumb to reach inward (uncomfortable for sustained aim)
Ability buttons fanned around aim stick may be too far from resting thumb position
Current MARGIN and FAN_RADIUS values don’t adapt between device sizes

Accessibility and customization

Dead Cells porting lesson: Players wanted ability to resize and reposition all buttons. No single layout satisfied all hand sizes and grip styles.

Precedent: Brawl Stars offers sensitivity sliders, haptic toggle, color blindness filters. Wild Rift (League of Legends mobile) has extensive button resize/reposition UI.

Current scheme lacks: Any in-game UI to adjust button size, position, or opacity. Tutorial assumes all players can access all buttons equally.

Opacity, visibility, and visual feedback

Current implementation strengths:

Ability buttons show charge state via animated arc (replaces HUD cooldown bar) ✓
Aim stick glow changes when engaged ✓
Move joystick dims and hides when idle ✓

Gaps:

Ability buttons lack haptic feedback on tap (Brawl Stars uses this heavily)
Pause button (static, top-right) lacks context—can be missed during hectic play
Ability button labels (WARP, DRONE) are small on fanned buttons; text clarity depends on button radius ≥15px

Candidate designs

Design A: Refined current (fanned buttons + improved accessibility)

Keep the floating left joystick + fixed aim stick + fanned ability buttons, but improve on pain points:

Changes:

Button size: Scale ability buttons to 44pt (52px) minimum for Apple HIG compliance
Pause button relocation: Move from top-right cluster to center-top or left-side pause zone (less chance of accidental press, clearer visual hierarchy)
iPad layout adaptation:
- Detect device size; on iPad, move ability fan arc inward (closer to thumb rest)
- Increase MARGIN and adjust FAN_RADIUS based on screen diagonal
Haptic feedback: Add Engine.get_main_physics_frame() or Input.vibrate_handheld() on dash/drone tap
In-game options screen: Add ability to adjust button scale (0.8x to 1.3x) and opacity (30%-100%)
Safe area respect: Query DisplayServer.screen_get_usable_rect() and inset pause/HUD buttons by at least 44pt

Pros:

Leverages existing working layout
Incremental improvements, lower risk
Tap-vs-hold drone behavior already working ✓

Cons:

Larger buttons consume more screen space (less room for gameplay)
iPad layout still requires device-detection branching
Pause button relocation requires playtesting to avoid confusion

Risk: swipe-for-ability on this design: No—keep ability buttons as-is. Swipe conflicts with aim flow.

Design B: Apple Touch Controller framework adoption (2026 feature)

Use Apple’s newly announced Touch Controller framework (WWDC 2026) instead of hand-rolling touch input:

How it works:

Framework provides 9 anchor points and groups controls (near-thumbs, top, bottom)
Automatically handles safe areas, Dynamic Island, home indicator
Adapts layout on iPad vs iPhone without manual branching
Renders with Metal for tight input latency

Changes:

Replace InputEventScreenTouch / InputEventScreenDrag parsing with TCTouchController descriptor setup
Define anchors: left-thumbstick (bottom-left), right-aim-stick (bottom-right), ability buttons (arc around aim), pause (top-right-safe)
Framework handles visibility toggle, adaptive sizing, and safe-area math automatically

Pros:

Apple’s own recommended approach (not a guess)
Automatic safe-area + notch handling
Potential for framework to improve between OS versions without code change
Haptic feedback and haptic patterns built-in

Cons:

Requires Godot 4.7+ with proper iOS Metal rendering (already using this ✓, but framework integration is new work)
Lock-in to Apple-provided aesthetics (button appearance constrained by framework)
Not suitable for custom “neon glowing ability buttons” visual direction (framework provides standard iOS look)
Overkill if Dark Cosmos neon aesthetic requires hand-rolled visuals

Risk: visual design constraint: The Touch Controller framework enforces an iOS-standard button appearance, which may conflict with Dark Cosmos’ neon aesthetic. Dead Cells and Brawl Stars both use custom hand-rolled buttons to maintain brand consistency.

Design C: Radial/gesture layer for secondary abilities (future-proof)

Current scheme handles dash + drone well. If Dark Cosmos adds more abilities post-v0.1:

Hybrid approach:

Keep dash + drone as fixed fanned buttons (primary layer)
Add optional radial menu overlay for non-critical actions (weapon swap, decoy mode toggle, etc.)
Long-hold on aim stick (or empty center screen area) reveals radial menu with 4-8 choices, drag to select

Pros:

Scales to many abilities without screen clutter
Gives each player a choice: buttons for muscle-memory actions, radial for less-frequent toggles
Separates “aim + fire” (button) from “configure + toggle” (radial)

Cons:

500ms hold delay breaks real-time flow if overused
Requires careful tuning to avoid opening mid-combat accidentally
Design only makes sense if there ARE secondary abilities needing a home

When to implement: Post-v0.1, only if roadmap adds 3+ new abilities.

Recommendation

Adopt Design A (refined current) for v0.1 release, with these immediate priorities:

Button size compliance (high): Scale WARP/DRONE to 44pt minimum. Reduces accessibility failures.
iPad layout detection (high): Detect iPad; increase MARGIN and adjust FAN_RADIUS so fanned buttons sit closer to thumb rest. Two-device testing should verify comfort.
Safe area handling (medium): Query DisplayServer safe insets; move pause/HUD toggle away from Dynamic Island on notched iPhones. Low-risk code addition.
Haptic feedback (medium): Add Input.vibrate_handheld() on dash/drone tap for tactile confirmation. Improves feel significantly with zero layout change.
In-game button customization (low, post-launch): Add settings screen to adjust button scale and opacity. Players will request this; defer to v0.1.1 if time-constrained.

Do NOT implement:

Swipe-to-dash on the aim thumb (conflicts with aim, high false-trigger risk)
Apple Touch Controller framework for v0.1 (overkill for current 2-ability layout, constrains neon aesthetic, delays ship)
Radial menu (no secondary abilities yet)

Rationale:

Vampire Survivors (the genre reference) and Dead Cells both use button-based ability layouts on mobile, not gestures for core mechanics
Current Dark Cosmos fanned-button design is proven (e.g., Brawl Stars super, Wild Rift abilities); refining it is lower-risk than a gesture pivot
Ability button charge arcs are already a Dark Cosmos signature; keeping that visual is a win
iPad and safe-area fixes are one-off code, not architectural changes

Post-v0.1 evolution:

Gather player feedback on button size and position (via TestFlight beta or App Store reviews)
If Touch Controller framework matures in iOS 18.x, revisit for v0.2 (lower risk once player expectations are set)
Design B becomes attractive if multiple neon-custom UI elements need coordinated safe-area handling