Commonwealth-Online-Public/server

Commonwealth Online Server - Quick Start

For Windows Users

Simply double-click start.bat to launch the server:

start.bat

The script will:

1. Check that Python 3.9+ is installed
2. Install required dependencies (typer, rich)
3. Generate a default commonwealth-server.json config file (if needed)
4. Start the server listening on 0.0.0.0:7777

First Run

On first run, a default commonwealth-server.json file is created in the server directory with these settings:

{
  "host": "0.0.0.0",
  "port": 7777,
  "server_name": "Commonwealth Online Server",
  "max_players": 16,
  "log_verbosity": "info"
}

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:

• host: Bind address (default 0.0.0.0 for all interfaces)
• port: Server port (default 7777)
• server_name: Display name
• max_players: Metadata for client displays
• log_verbosity: debug, info, warning, or error

Connecting Clients

Once the server is running:

• 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

Stopping the Server

Press Ctrl+C in the terminal to stop the server gracefully.

---

For Advanced Users (Command Line)

If you prefer command-line usage, use the CLI directly:

cd server
pip install -r requirements.txt

# Generate config
python consumer_server_cli.py config init my-config.json

# Start server
python consumer_server_cli.py serve --config my-config.json

# Check server status (from another terminal)
python consumer_server_cli.py status

# List connected clients
python consumer_server_cli.py clients

# Set in-game time
python consumer_server_cli.py world time 1430

# Set weather
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:

# 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:

python consumer_server_cli.py serve --config commonwealth-server.json --port 8000