Add port troubleshooting and fix script

- Add fix-port.bat to handle 'port already in use' errors
- Detect blocking process and kill it, or prompt to use different port
- Updated start.bat to detect startup failures and offer fix
- Updated README.md with troubleshooting guide for port conflicts

Users can now easily resolve port 7777 conflicts by running fix-port.bat
or using --port override on the CLI.

Co-authored-by: Cursor <cursoragent@cursor.com>

server/README.md

@@ -28,6 +28,23 @@ On first run, a default `commonwealth-server.json` file is created in the server
 }
 ```
 
+### Port Already in Use?
+
+If you get an error like "Only one usage of each socket address ... is normally permitted", port 7777 is already in use by another process.
+
+**Option 1: Kill the blocking process**
+
+Run `fix-port.bat` to:
+- Detect which process is using port 7777
+- Kill the process
+- Restart the server
+
+**Option 2: Use a different port**
+
+Run `fix-port.bat` and select "Use a different port" to change the port in your config file.
+
+Alternatively, manually edit `commonwealth-server.json` and change the `"port"` value to something like `7778`, `8000`, or `9999`.
+
 ### Customizing the Server
 
 Edit `commonwealth-server.json` to customize:
@@ -41,7 +58,7 @@ Edit `commonwealth-server.json` to customize:
 
 Once the server is running:
 
-- **Local PC**: Connect to `127.0.0.1:7777`
+- **Local PC**: Connect to `127.0.0.1:7777` (or your custom port)
 - **LAN**: Connect to your PC's local IP (displayed on startup, e.g., `192.168.1.64:7777`)
 - **Remote**: Forward port 7777/TCP on your router and use your public IP
 
@@ -79,3 +96,20 @@ python consumer_server_cli.py world weather 0002b52a
 ```
 
 Run `python consumer_server_cli.py --help` to see all available commands.
+
+### Troubleshooting: Port in Use
+
+If using the CLI, manually change the port:
+
+```bash
+# Generate config with custom port
+python consumer_server_cli.py config init my-config.json
+# Edit my-config.json and change "port" to a different number
+python consumer_server_cli.py serve --config my-config.json --port 8000
+```
+
+Or use the CLI port override:
+
+```bash
+python consumer_server_cli.py serve --config commonwealth-server.json --port 8000
+```

server/fix-port.bat

@@ -0,0 +1,110 @@
+@echo off
+setlocal enabledelayedexpansion
+
+echo.
+echo ================================================================================
+echo  Commonwealth Online - Port 7777 in Use
+echo ================================================================================
+echo.
+echo Port 7777 is currently in use by another process.
+echo.
+echo Options:
+echo   1. Kill the process using port 7777 and restart server
+echo   2. Use a different port (you will be prompted to enter one)
+echo   3. Cancel and exit
+echo.
+
+choice /C 123 /N /M "Select option (1-3): "
+set choice=%errorlevel%
+
+if %choice%==1 goto kill_process
+if %choice%==2 goto change_port
+if %choice%==3 goto exit_script
+
+:kill_process
+echo.
+echo Finding process using port 7777...
+for /f "tokens=5" %%a in ('netstat -aon ^| find ":7777"') do (
+    set PID=%%a
+)
+
+if defined PID (
+    echo Killing process with PID !PID!...
+    taskkill /PID !PID! /F >nul 2>&1
+    if errorlevel 1 (
+        echo ERROR: Could not kill process. Try running this script as Administrator.
+        pause
+        exit /b 1
+    )
+    echo Process killed successfully.
+    echo.
+    echo Waiting for port to be released...
+    timeout /t 2 /nobreak
+    echo.
+    echo Restarting server...
+    call start.bat
+) else (
+    echo Could not determine which process is using port 7777.
+    echo Try:
+    echo   - Restarting your computer
+    echo   - Running as Administrator
+    echo   - Or choose option 2 to use a different port
+    pause
+    exit /b 1
+)
+goto end
+
+:change_port
+echo.
+set /p NEW_PORT="Enter desired port (1024-65535, default is 7777): "
+
+if "!NEW_PORT!"=="" (
+    set NEW_PORT=7777
+)
+
+REM Validate port is a number between 1024 and 65535
+for /f "delims=0123456789" %%A in ("!NEW_PORT!") do (
+    echo ERROR: Port must be a number.
+    pause
+    exit /b 1
+)
+
+if !NEW_PORT! lss 1024 (
+    echo ERROR: Port must be 1024 or higher.
+    pause
+    exit /b 1
+)
+
+if !NEW_PORT! gtr 65535 (
+    echo ERROR: Port must be 65535 or lower.
+    pause
+    exit /b 1
+)
+
+echo.
+echo Updating commonwealth-server.json to use port !NEW_PORT!...
+
+REM Create new config with updated port
+(
+    echo {
+    echo   "host": "0.0.0.0",
+    echo   "port": !NEW_PORT!,
+    echo   "server_name": "Commonwealth Online Server",
+    echo   "max_players": 16,
+    echo   "log_verbosity": "info"
+    echo }
+) > commonwealth-server.json
+
+echo Config updated. Starting server on port !NEW_PORT!...
+echo.
+python consumer_server_cli.py serve --config commonwealth-server.json
+
+goto end
+
+:exit_script
+echo.
+echo Cancelled.
+exit /b 0
+
+:end
+pause

server/start.bat

@@ -48,4 +48,17 @@ echo.
 
 python consumer_server_cli.py serve --config commonwealth-server.json
 
+REM Check if the error was port in use
+if errorlevel 1 (
+    echo.
+    echo Server failed to start. If you see "Only one usage of each socket address"
+    echo error, the port may already be in use.
+    echo.
+    choice /C YN /N /M "Would you like to fix the port issue? (Y/N): "
+    if !errorlevel!==1 (
+        echo.
+        call fix-port.bat
+    )
+)
+
 pause