Build a multiplayer competitive Pac-Man game as a single Python file (game.py) using websockets 13.x.
## Game Design
1-2 players compete on the SAME maze simultaneously. If only one player joins, the game starts in single-player mode after 10 seconds (or immediately with a "Start Solo" button). When a second player joins, the next round becomes competitive. The goal: eat more dots than your opponent before time runs out (90 seconds). In single player, just go for the high score.
### Maze & Dots
- Generate a classic pac-man style maze (walls, corridors, open areas) — at least 25x25 grid
- Fill corridors with regular dots (1 point each)
- Place 8 bonus dots (big flashing ones, 10 points each) in strategic locations
- Dots disappear when ANY player eats them — it's a race
### Players
- Player 1: yellow pac-man, starts top-left
- Player 2: cyan pac-man, starts bottom-right
- Smooth movement with WASD keys
- Mouth animation (classic open/close)
- Players can pass through each other (no collision between players)
### Ghosts (4 total)
- Each ghost has a different color and personality:
- Red: chases the nearest player directly
- Pink: tries to ambush (targets 4 tiles ahead of nearest player)
- Blue: random patrol, switches to chase if player is within 5 tiles
- Orange: alternates between chase and scatter every 10 seconds
- If a ghost catches you: 3-second respawn at your start position + lose 5 points
- Ghosts respawn from center after 5 seconds if stuck
### Bonus Power-ups (4 on the map, respawn every 30s)
- Eating a power pellet makes ghosts vulnerable for 8 seconds (turn blue, move slower)
- Eating a vulnerable ghost: +20 points, ghost respawns at center
### Game Speed — IMPORTANT
- The server game loop MUST run at a FIXED tick rate using delta-time, not as fast as the CPU allows
- Target: 10 ticks per second (100ms per tick). Use a proper game loop that sleeps for the remainder of each tick
- Movement: players move exactly 1 tile per tick when holding a direction key — no faster
- Client renders at 15 FPS interpolating between server states for smoothness
- Do NOT use asyncio.sleep(0) or tight loops — use asyncio.sleep(tick_interval - elapsed) to maintain consistent speed regardless of server performance
### UI Requirements
- Dark background (#0a0a0a), neon-colored maze walls
- Live scoreboard showing both players' scores, time remaining
- "PLAYER 1 WINS" / "PLAYER 2 WINS" / "TIE" screen at end with rematch button
- In single player: show "YOUR SCORE" and personal best
- Lobby screen: shows connected players, "Start Solo" button, game auto-starts when 2 players ready
- Mobile-friendly: add on-screen d-pad controls for touch
- Sound effects using Web Audio API (dot eat, ghost eat, death, game start, game end)
- Show the HLE tunnel URL and PIN prominently on the game page — display a small info bar or banner (top or bottom of the page) showing "Share this URL: <tunnel-url>" and "PIN: <pin>" so the host can easily share access with friends. The server should accept these as command-line arguments: `python game.py --url <tunnel-url> --pin <pin>`
### Technical
- Python websockets 13.x server on port 19265 (non-standard to avoid conflicts)
- ALL HTML/CSS/JS inline in the Python file (served via HTTP on same port)
- Game state runs server-side (authoritative server — no cheating)
- Client sends inputs, server sends game state at the fixed tick rate via websocket
- Handle disconnection gracefully (in 2P: other player wins if opponent leaves; in 1P: game just ends)
## Step 1: Environment discovery
BEFORE writing any code, create and run a discovery script (`check_env.sh`) that detects the local environment:
```bash
#!/usr/bin/env bash
echo "=== Environment Discovery ==="
echo "Python3: $(which python3 2>/dev/null || echo 'NOT FOUND')"
echo "Python: $(which python 2>/dev/null || echo 'NOT FOUND')"
echo "Pip: $(which pip3 2>/dev/null || which pip 2>/dev/null || echo 'NOT FOUND')"
echo "HLE: $(which hle 2>/dev/null || echo 'NOT FOUND')"
echo "Curl: $(which curl 2>/dev/null || echo 'NOT FOUND')"
echo "Python version: $(python3 --version 2>/dev/null || python --version 2>/dev/null)"
# Check if HLE is already configured
if [ -f "$HOME/.config/hle/config.toml" ]; then
echo "HLE config: FOUND at ~/.config/hle/config.toml"
grep -o 'api_key = "hle_[a-f0-9]\{4\}' "$HOME/.config/hle/config.toml" 2>/dev/null && echo "...key present" || echo "...no key"
else
echo "HLE config: NOT FOUND"
fi
echo "Port 19265: $(lsof -i :19265 2>/dev/null && echo 'IN USE' || echo 'available')"
```
Use the detected paths (e.g., `python3` vs `python`) for ALL subsequent commands. Store them as variables for the start script. If python3 isn't found, stop and tell me. Do NOT ask me to confirm tool paths — use whatever was detected.
## Step 2: Set up venv and install dependencies
Create a virtual environment and install dependencies. Do NOT install packages globally.
```
python3 -m venv .venv
source .venv/bin/activate
pip install 'websockets>=13,<14' hle-client
```
After installing, verify both are available:
```
timeout 5 .venv/bin/python -c "import websockets; print('websockets OK')"
timeout 5 .venv/bin/hle --version
```
Use `timeout` (or `gtimeout` on macOS) as a prefix for ANY command that should complete quickly, to avoid hanging forever. If `timeout` isn't available, use Python's subprocess with a timeout instead.
## Step 3: Verify HLE is set up
Run `timeout 10 .venv/bin/hle auth status` to check if HLE is configured with a valid API key.
If NOT configured (no API key found), or if the command fails, guide me through this one-time setup:
1. Run: `.venv/bin/hle auth login`
- This opens my browser to hle.world/dashboard
- Create a free account with Google or GitHub
- Generate an API key and save it when prompted
- This key is now saved locally — I won't need to do this again
2. Verify it worked: `timeout 10 .venv/bin/hle auth status` should show the saved key
## Step 4: Build the game
Create game.py with the full implementation described above.
## Step 5: Create the start script
Create `start.sh` that automates everything end-to-end. Running `./start.sh` should be the ONLY thing needed:
```bash
#!/usr/bin/env bash
set -euo pipefail
GAME_PORT=19265
LABEL="pacman"
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
cd "$SCRIPT_DIR"
# --- Venv setup ---
if [ ! -d .venv ]; then
python3 -m venv .venv
.venv/bin/pip install -q 'websockets>=13,<14' hle-client
fi
PYTHON=".venv/bin/python"
HLE=".venv/bin/hle"
# --- Check HLE auth ---
if ! timeout 10 "$HLE" auth status >/dev/null 2>&1; then
echo "HLE not configured. Run: $HLE auth login"
exit 1
fi
# --- Read API key from config for direct API calls ---
API_KEY=$(grep -oP 'api_key = "\K[^"]+' "$HOME/.config/hle/config.toml" 2>/dev/null || echo "")
if [ -z "$API_KEY" ]; then
echo "Could not read API key from ~/.config/hle/config.toml"
exit 1
fi
# --- Generate random 6-digit PIN ---
PIN=$(printf "%06d" $((RANDOM % 1000000)))
# --- Start game server ---
"$PYTHON" game.py &
GAME_PID=$!
sleep 2
# --- Start HLE tunnel in background, capture URL ---
"$HLE" expose --service "http://localhost:$GAME_PORT" --label "$LABEL" > hle.log 2>&1 &
HLE_PID=$!
# Wait for tunnel URL to appear in log (up to 15s)
TUNNEL_URL=""
for i in $(seq 1 30); do
TUNNEL_URL=$(grep -oP 'https://[^ ]+\.hle\.world' hle.log 2>/dev/null | head -1 || true)
[ -n "$TUNNEL_URL" ] && break
sleep 0.5
done
if [ -z "$TUNNEL_URL" ]; then
echo "Failed to get tunnel URL. Check hle.log"
kill $GAME_PID $HLE_PID 2>/dev/null
exit 1
fi
# --- Set PIN via HLE API (non-interactive, no CLI prompts) ---
# Extract subdomain from URL (e.g., pacman-x7k from https://pacman-x7k.hle.world)
SUBDOMAIN=$(echo "$TUNNEL_URL" | sed 's|https://||;s|\.hle\.world.*||')
curl -s -X PUT "https://hle.world/api/tunnels/$SUBDOMAIN/pin" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d "{\"pin\": \"$PIN\"}"
# --- Restart game with URL and PIN displayed ---
kill $GAME_PID 2>/dev/null; wait $GAME_PID 2>/dev/null
"$PYTHON" game.py --url "$TUNNEL_URL" --pin "$PIN" &
GAME_PID=$!
# --- Print sharing info ---
echo ""
echo "╔══════════════════════════════════════════╗"
echo "║ GAME READY — share with your friend: ║"
echo "║ ║"
echo "║ URL: $TUNNEL_URL"
echo "║ PIN: $PIN"
echo "║ ║"
echo "╚══════════════════════════════════════════╝"
echo ""
echo "Press Ctrl+C to stop."
# --- Cleanup on exit ---
cleanup() { kill $GAME_PID $HLE_PID 2>/dev/null; rm -f hle.log; }
trap cleanup EXIT INT TERM
wait
```
Key requirements for the script:
- Use full paths to `.venv/bin/python` and `.venv/bin/hle` — never rely on `PATH` or `source activate`
- Track process IDs with `$!` after backgrounding — NEVER use `pkill` or `killall`
- Set the PIN via the HLE REST API using curl (`PUT https://hle.world/api/tunnels/{subdomain}/pin` with `Authorization: Bearer {api_key}` header and `{"pin": "..."}` body) — do NOT use `hle pin set` as it requires interactive input that cannot be piped
- Use `timeout` prefix for any command expected to finish quickly
- Use port 19265 (not 8765) to avoid conflicts
Make start.sh executable with `chmod +x start.sh`.
## Step 6: Test it
Run `./start.sh` and show me the tunnel URL and PIN. I'll send them to my friend so they can join.