Project Zomboid Setup Guide

Complete guide for setting up automatic item delivery on your Project Zomboid dedicated server using the Pixlpay Go Agent.

Prerequisites

Before you begin, ensure you have:

• A running Project Zomboid dedicated server
• Admin access to the server configuration files
• Your Pixlpay store credentials (Store Secret & Server Secret)

Step 1: Enable RCON on Your Server

Locate Your Server Configuration

Your server configuration file is typically located at:

Windows:

C:\Users\[Username]\Zomboid\Server\servertest.ini

Linux:

/home/[username]/Zomboid/Server/servertest.ini

TIP

Replace servertest with your actual server name if different.

Enable RCON Settings

Open the configuration file and find/add these settings:

# Enable RCON
RCONPort=27015
RCONPassword=your_secure_password_here

Security

• Use a strong, unique password (at least 16 characters)
• Never share your RCON password publicly
• The RCON port should be different from your game port

Restart Your Server

After saving the configuration, restart your Project Zomboid server for changes to take effect.

Step 2: Download and Configure the Agent

Download the Agent

Download the appropriate version for your server's operating system:

Platform	File
Windows	store-agent.exe
Linux	store-agent-linux

Downloads are available from your Pixlpay dashboard under Settings > Game Servers > Downloads.

Create Configuration File

Create a pixlpay-config.json file in the same directory as the agent:

{
    "platform_url": "https://api.pixlpay.com",
    "store_secret": "YOUR_STORE_SECRET",
    "server_secret": "YOUR_SERVER_SECRET",
    "game_type": "project_zomboid",
    "rcon_host": "127.0.0.1",
    "rcon_port": 27015,
    "rcon_password": "your_rcon_password_here",
    "debug_mode": false
}

Configuration Fields

Field	Description	Example
platform_url	Pixlpay API endpoint	https://api.pixlpay.com
store_secret	Your store's API key	pk_live_xxx...
server_secret	This server's unique key	sk_server_xxx...
game_type	Must be project_zomboid	project_zomboid
rcon_host	RCON server address	127.0.0.1
rcon_port	RCON port from server config	27015
rcon_password	RCON password from server config	your_password
debug_mode	Enable verbose logging	false

Finding Your Secrets

1. Log in to your Pixlpay dashboard
2. Navigate to Settings > Game Servers
3. Click on your Project Zomboid server (or add one)
4. Copy the Store Secret and Server Secret

Step 3: Test the Connection

Run the Agent in Interactive Mode

# Windows
./store-agent.exe -interactive

# Linux
./store-agent-linux -interactive

Verify RCON Connection

You should see output like:

========================================
     PixlPay Store Agent v1.0.0
========================================
Game Type:    project_zomboid
RCON Target:  127.0.0.1:27015
API Endpoint: https://api.pixlpay.com
========================================
Connecting to RCON at 127.0.0.1:27015...
RCON connection established!
Agent ready! Polling every 60s, heartbeat every 2m0s

Test API Connection

In interactive mode, type:

> test

Expected output:

Testing API connection...
Connection successful! API returned status 200.
Server recognized: My PZ Server (ID: 123)
Pending commands: 0

Step 4: Configure Products

Setting Up Delivery Commands

In your Pixlpay dashboard, when creating products, use Project Zomboid server commands in the delivery command field.

Available Placeholders

Placeholder	Description	Example Value
{player}	Player's username	SurvivorSteve
{username}	Same as {player}	SurvivorSteve
{quantity}	Quantity purchased	5
{product_name}	Name of the product	VIP Kit
{order_id}	Order ID	12345

Example Commands

Give Items:

additem {player} Base.Axe 1
additem {player} Base.RifleHunting 1
additem {player} Base.Bullets9mmBox 5

Set Access Level (Admin/Moderator):

setaccesslevel {player} admin
setaccesslevel {player} moderator

Add Experience:

addxp {player} Strength 500
addxp {player} Fitness 500
addxp {player} Aiming 1000

Server Message:

servermsg "Welcome VIP member {player}!"

Multiple Commands (one per line):

additem {player} Base.Axe 1
additem {player} Base.Bag_BigHikingBag 1
addxp {player} Strength 200
servermsg "{player} just purchased the Starter Kit!"

Common Item IDs

Item	ID
Axe	Base.Axe
Baseball Bat	Base.BaseballBat
Hunting Rifle	Base.RifleHunting
Shotgun	Base.Shotgun
9mm Pistol	Base.Pistol
9mm Ammo Box	Base.Bullets9mmBox
Shotgun Shells	Base.ShotgunShellsBox
First Aid Kit	Base.FirstAidKit
Big Hiking Bag	Base.Bag_BigHikingBag
Water Bottle	Base.WaterBottleFull
Canned Food	Base.CannedBeans
Generator	Base.Generator
Hammer	Base.Hammer
Nails Box	Base.NailsBox
Plank	Base.Plank

TIP

For a complete list of item IDs, check the Project Zomboid Wiki or use the in-game item browser.

Step 5: Run as a Service

Windows (Using NSSM)

1. Download NSSM from https://nssm.cc/download
2. Open Command Prompt as Administrator
3. Run:

nssm install PixlPayAgent "C:\path\to\store-agent.exe"
nssm set PixlPayAgent AppDirectory "C:\path\to"
nssm set PixlPayAgent DisplayName "PixlPay Delivery Agent"
nssm set PixlPayAgent Description "Automatic delivery agent for Project Zomboid"
nssm set PixlPayAgent Start SERVICE_AUTO_START
nssm start PixlPayAgent

Linux (Using systemd)

1. Create the service file:

sudo nano /etc/systemd/system/pixlpay-agent.service

2. Add the following content:

[Unit]
Description=PixlPay Delivery Agent for Project Zomboid
After=network.target

[Service]
Type=simple
User=pzserver
WorkingDirectory=/home/pzserver/pixlpay
ExecStart=/home/pzserver/pixlpay/store-agent-linux
Restart=always
RestartSec=10
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target

3. Enable and start the service:

sudo systemctl daemon-reload
sudo systemctl enable pixlpay-agent
sudo systemctl start pixlpay-agent

4. Check status:

sudo systemctl status pixlpay-agent
journalctl -u pixlpay-agent -f  # Follow logs

Troubleshooting

RCON Connection Failed

Symptoms:

[WARN] [Attempt 1] RCON connection failed: dial tcp 127.0.0.1:27015: connection refused

Solutions:

1. Verify your PZ server is running
2. Check RCONPort in servertest.ini matches pixlpay-config.json
3. Ensure RCON password is correct (no extra spaces)
4. Check firewall isn't blocking the port:

# Windows
netstat -an | findstr 27015

# Linux
ss -tlnp | grep 27015

Authentication Failed

Symptoms:

[ERROR] Poll failed: authentication failed (HTTP 401)

Solutions:

1. Verify Store Secret and Server Secret are correct
2. Check your store is approved in the Pixlpay dashboard
3. Ensure the server is registered and active
4. Try regenerating the Server Secret in your dashboard

Command Execution Failed

Symptoms:

[ERROR] Command execution failed: PZ Execution Error: ...

Solutions:

1. Test the command manually in PZ server console
2. Check player username spelling/format
3. Verify item IDs are correct
4. Some commands may require the player to be online

Player Not Found

Symptoms: Commands execute but nothing happens in-game.

Solutions:

1. Ensure the username exactly matches (case-sensitive)
2. Player may need to be online for some commands
3. Check server logs for any errors

Firewall Configuration

Windows Firewall

# Allow RCON port (run as Administrator)
netsh advfirewall firewall add rule name="PZ RCON" dir=in action=allow protocol=tcp localport=27015

Linux (UFW)

sudo ufw allow 27015/tcp comment "PZ RCON"

Linux (iptables)

sudo iptables -A INPUT -p tcp --dport 27015 -j ACCEPT

Security Best Practices

1. Use localhost when possible - If the agent runs on the same machine as PZ server, use 127.0.0.1
2. Strong RCON password - Use at least 16 random characters
3. Restrict RCON access - Only allow connections from trusted IPs
4. Keep secrets secure - Never commit pixlpay-config.json to version control
5. Monitor logs - Regularly check for unauthorized access attempts

Directory Structure

Recommended setup:

/home/pzserver/pixlpay/
├── store-agent-linux       # The agent executable
├── pixlpay-config.json     # Your configuration
├── data/
│   └── agent_data.json     # Persistent data (auto-created)
└── logs/
    ├── pixlpay-general_2025-01-15.log
    ├── pixlpay-deliveries_2025-01-15.log
    └── pixlpay-errors_2025-01-15.log

Support

If you encounter issues not covered here:

1. Enable debug mode: Set "debug_mode": true in pixlpay-config.json
2. Check logs in the logs/ directory
3. Run in interactive mode and use status command
4. Contact support with your logs