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

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

curl: Connection refused

state.scene

/nodes

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