macOS Game Testing for Nathaniel

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

Key Insight: Use GameCommandServer for All Interaction

The game uses SpriteKit with custom scene coordinates. Unlike iOS Simulator, there are no reliable external UI automation tools for macOS SpriteKit games.

Always use the GameCommandServer HTTP API (port 8765) for:

• Navigating menus
• Clicking buttons
• Getting game state
• Interacting with gameplay
• Taking screenshots

XcodeBuildMCP is used only for: building, running, and stopping the app.

Quick Start: Test a Feature

# 1. Build and run the macOS app
mcp__XcodeBuildMCP__build_run_macos

# 2. Wait 2-3 seconds for app 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
curl -s http://localhost:8765/action -X POST -H "Content-Type: application/json" -d '{"name":"startGame"}'

Testing Workflow

Step 1: Setup and Build

# Set session defaults for XcodeBuildMCP
mcp__XcodeBuildMCP__session-set-defaults:
  projectPath: /Users/ruairi/dev/Nathaniel/Nathaniel.xcodeproj
  scheme: Nathaniel macOS

# Build and run (opens the app automatically)
mcp__XcodeBuildMCP__build_run_macos

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 clickable elements with frame coordinates

Click 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

Get screenshot from GameCommandServer and save to file:

# Save screenshot as PNG file
curl -s http://localhost:8765/screenshot | jq -r .data | base64 -d > /tmp/macos-screenshot.png

# View the screenshot
open /tmp/macos-screenshot.png

Or use macOS screencapture for the entire window:

# Capture the Nathaniel window
screencapture -l $(osascript -e 'tell app "Nathaniel" to id of window 1') /tmp/nathaniel-window.png

Step 6: Stop the App

mcp__XcodeBuildMCP__stop_mac_app:
  appName: Nathaniel

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

• moveHermes

  (params: x, y) - Move Hermes to position

• targetEnemy

  (params: index) - Target enemy by index

OptionsScene / CreditsScene

• back

  - Return to main menu

DevSettings (DEBUG Builds Only)

Adjust game settings for easier testing:

# Get current settings
curl -s http://localhost:8765/settings | jq .

# Make player invincible
curl -s http://localhost:8765/settings -X POST \
  -H "Content-Type: application/json" \
  -d '{"playerInvincible": true}'

# Give infinite resources
curl -s http://localhost:8765/settings -X POST \
  -H "Content-Type: application/json" \
  -d '{"infiniteResources": true}'

# Reset all settings to defaults
curl -s http://localhost:8765/settings/reset -X POST

Common Test Scenarios

Test Menu Navigation

# Start at main menu
curl -s http://localhost:8765/state | jq '.scene'
# Should be "MainMenuScene"

# Go to level select
curl -s http://localhost:8765/action -X POST -d '{"name":"startGame"}'
sleep 0.5
curl -s http://localhost:8765/state | jq '.scene'
# Should be "LevelSelectScene"

# Go back
curl -s http://localhost:8765/action -X POST -d '{"name":"back"}'
sleep 0.5
curl -s http://localhost:8765/state | jq '.scene'
# Should be "MainMenuScene"

Test Gameplay

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

# Check initial state
curl -s http://localhost:8765/state | jq '{scene, lives, enemyCount}'

# Select Hermes and move
curl -s http://localhost:8765/action -X POST -d '{"name":"selectHermes"}'
curl -s http://localhost:8765/action -X POST -d '{"name":"moveHermes","params":{"x":"600","y":"400"}}'

Test Character Toggle

# In GameScene, toggle between characters
curl -s http://localhost:8765/action -X POST -d '{"name":"toggleCharacter"}'
sleep 0.5
# Take screenshot to verify camera moved
curl -s http://localhost:8765/screenshot | jq -r .data | base64 -d > /tmp/after-toggle.png

Troubleshooting

curl: Connection refused

state.scene

/nodes

xcodebuild -version

pkill -f Nathaniel

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 (window is wider than tall)
• Port 8765 is shared between iOS Simulator and macOS - only run one at a time