iOS Game Testing for Nathaniel

This skill provides reliable testing of the Nathaniel SpriteKit game using the embedded GameCommandServer HTTP API.

Key Insight: Use GameCommandServer, Not XcodeBuildMCP UI Tools

IMPORTANT: The game is a landscape SpriteKit game. XcodeBuildMCP's tap, describe_ui, and other UI interaction tools have coordinate transformation issues with landscape games.

Always use the GameCommandServer HTTP API (port 8765) for UI interaction instead. It works directly with SpriteKit scene coordinates and is far more reliable.

Quick Start: Test a Feature

# 1. Build and run (sets up session defaults automatically)
# Use XcodeBuildMCP to build and launch

# 2. Wait for game to load, then check server health
curl -s http://localhost:8765/health

# 3. Get current game state
curl -s http://localhost:8765/state | jq .

# 4. Navigate and interact using actions (preferred) or taps
curl -s http://localhost:8765/action -X POST -H "Content-Type: application/json" -d '{"name":"startGame"}'

Testing Workflow

Step 1: Setup Simulator and Build

# Set session defaults for XcodeBuildMCP
mcp__XcodeBuildMCP__session-set-defaults:
  projectPath: /Users/ruairi/dev/Nathaniel/Nathaniel.xcodeproj
  scheme: Nathaniel iOS
  simulatorId: <UUID from list_sims with iOS 26.1+>
  useLatestOS: true

# Build and run
mcp__XcodeBuildMCP__build_run_sim

Simulator Requirements: Use iOS 26.1+ simulators (iPhone 17 Pro, etc.)

Step 2: Wait for GameCommandServer

After the app launches, wait 2-3 seconds, then verify the server is running:

# Check health - should return {"status":"ok"}
curl -s http://localhost:8765/health

If it fails, the app may not have fully launched. Wait and retry.

Step 3: Navigate to Test Location

Use the HTTP API to navigate through menus:

Main Menu -> Level Select:

curl -s http://localhost:8765/action -X POST \
  -H "Content-Type: application/json" \
  -d '{"name":"startGame"}'

Level Select -> Level 1:

curl -s http://localhost:8765/action -X POST \
  -H "Content-Type: application/json" \
  -d '{"name":"level_1"}'

Step 4: Interact with Game

Get game state:

curl -s http://localhost:8765/state | jq .
# Returns: scene, score, lives, resources, playerPosition, hermesPosition, enemyCount

Get interactive nodes:

curl -s http://localhost:8765/nodes | jq .
# Returns: all tappable elements with frame coordinates

Tap at coordinates (scene coordinates, not screen):

curl -s http://localhost:8765/tap -X POST \
  -H "Content-Type: application/json" \
  -d '{"x": 500, "y": 300}'

Execute named actions:

# Select characters
curl -s http://localhost:8765/action -X POST -d '{"name":"selectNathaniel"}'
curl -s http://localhost:8765/action -X POST -d '{"name":"selectHermes"}'

# Toggle between characters (switches and animates camera)
curl -s http://localhost:8765/action -X POST -d '{"name":"toggleCharacter"}'

# Move character
curl -s http://localhost:8765/action -X POST -d '{"name":"moveNathaniel","params":{"x":"500","y":"300"}}'

# Target enemy
curl -s http://localhost:8765/action -X POST -d '{"name":"targetEnemy","params":{"index":"0"}}'

Step 5: Visual Verification

Use XcodeBuildMCP screenshot for visual verification (this works fine):

mcp__XcodeBuildMCP__screenshot

Or get base64 screenshot from GameCommandServer:

curl -s http://localhost:8765/screenshot | jq -r .data | base64 -d > screenshot.png

Available Actions by Scene

MainMenuScene

• startGame - Go to level select
• options - Open options
• credits - Open credits

LevelSelectScene

• level_1 through level_5 - Start specific level
• back - Return to main menu

GameScene

• selectNathaniel - Select Nathaniel
• selectHermes - Select Hermes
• toggleCharacter - Toggle between Nathaniel and Hermes (animates camera)
• moveNathaniel (params: x, y) - Move to position
• targetEnemy (params: index) - Target enemy by index

OptionsScene / CreditsScene

• back - Return to main menu

Common Test Scenarios

Test Character Toggle Button

# Navigate to level 1
curl -s http://localhost:8765/action -X POST -d '{"name":"startGame"}'
sleep 1
curl -s http://localhost:8765/action -X POST -d '{"name":"level_1"}'
sleep 2

# Check initial state (should be Nathaniel selected)
curl -s http://localhost:8765/state | jq '.playerPosition, .hermesPosition'

# Get nodes to find toggle button
curl -s http://localhost:8765/nodes | jq '.[] | select(.name | contains("toggle"))'

# Tap the toggle button (find coordinates from nodes)
# Or tap in the HUD area where the toggle button should be

Test Camera Follows Character

# Get initial camera position (check state)
curl -s http://localhost:8765/state

# Select Hermes (should animate camera to Hermes)
curl -s http://localhost:8765/action -X POST -d '{"name":"selectHermes"}'

# Wait for animation
sleep 0.5

# Check state again - camera should have moved toward Hermes
curl -s http://localhost:8765/state

Troubleshooting

| Issue | Solution | |-------|----------| | curl: Connection refused | App not running or GameCommandServer not started (DEBUG builds only) | | Actions return "not found" | Wrong scene - check state.scene first | | Taps don't work | Verify coordinates are in scene space (use /nodes to get frames) | | Build fails | Check simulator UUID is iOS 26.1+, run list_sims |

Important Notes

• GameCommandServer only runs in DEBUG builds
• Scene coordinates: origin (0,0) is bottom-left, scene size is 1366x1024
• Bundle ID: com.ruarfff.Nathaniel
• The game runs in landscape mode