Valheim Plugin (BepInEx)

The Pixlpay Valheim plugin automatically delivers purchased items to players on your Valheim dedicated server using BepInEx.

Features

• Native BepInEx integration
• Automatic polling for pending deliveries
• Support for purchases, refunds, and chargebacks
• Online player queuing
• Item spawning via Server devcommands
• Detailed logging

Requirements

1. BepInExPack Valheim (v5.4.22+)

   • Download: Thunderstore
   • Provides the mod framework for Valheim servers

2. Server devcommands by JereKuusela

   • Download: Thunderstore
   • Required dependency - enables console command execution on dedicated servers
   • Without this mod, spawn commands will not work on dedicated servers

Installation

Step 1: Install BepInEx

1. Download BepInExPack Valheim from Thunderstore
2. Extract to your Valheim server directory
3. The folder structure should look like:

valheim_server/
├── BepInEx/
│   ├── config/
│   ├── plugins/
│   └── ...
├── valheim_server.exe
└── ...

Step 2: Install Server devcommands

1. Download Server devcommands from Thunderstore
2. Copy ServerDevcommands.dll to BepInEx/plugins/

Step 3: Install PixlPay

Download PixlPay.cs

Or get it from your Pixlpay Dashboard under Settings > Game Servers > Downloads.

1. Copy PixlPay.cs to BepInEx/plugins/
2. Start the server once to generate the config file
3. Stop the server and configure the plugin

Configuration

After first run, edit BepInEx/config/com.pixlpay.valheim.cfg:

[Authentication]

## Your PixlPay store secret key. Find this in your PixlPay dashboard under Game Servers.
# Setting type: String
# Default value:
StoreSecret = your_store_secret_here

## Your game server's secret key. Find this in your PixlPay dashboard under Game Servers.
# Setting type: String
# Default value:
ServerSecret = your_server_secret_here

[Debug]

## Enable debug logging for troubleshooting.
# Setting type: Boolean
# Default value: false
DebugMode = false

## Enable development mode to use a custom API URL.
# Setting type: Boolean
# Default value: false
DevMode = false

## Custom API URL for development mode.
# Setting type: String
# Default value: http://localhost:8000
DevApiUrl = http://localhost:8000

Configuration Options

Option	Default	Description
StoreSecret	""	Your store's secret key (shared across all servers)
ServerSecret	""	This specific server's secret key (unique per server)
DebugMode	false	Enable verbose logging for troubleshooting
DevMode	false	Use DevApiUrl instead of production API (https://api.pixlpay.net)
DevApiUrl	http://localhost:8000	Custom API URL when DevMode is enabled

Getting Your Secrets

1. Log in to your Pixlpay Dashboard
2. Go to Settings > Game Servers
3. Add your Valheim server or select an existing one
4. Copy the Store Secret and Server Secret

How It Works

1. Polling: The plugin polls the Pixlpay API every 60 seconds for pending deliveries
2. Heartbeat: Plugin sends a heartbeat every 120 seconds to report server status
3. Execution: Commands are executed via Server devcommands when conditions are met
4. Confirmation: Results are reported back to the API
5. Offline Queue: If a player is offline and the product requires online delivery, the command is queued
6. Online Check: Queued commands are checked every 30 seconds for eligible players

Timing Constants

Constant	Value	Purpose
Polling Interval	60 seconds	Time between API polls for pending commands
Online Check Interval	30 seconds	Time between checks for queued commands
Heartbeat Interval	120 seconds	Time between heartbeat status updates
Request Timeout	10 seconds	HTTP request timeout
Max Consecutive Failures	5	Failures before warning is logged

Execution Modes

Mode	Behavior
Instant	Commands execute immediately, even if player is offline
When Online	Commands are queued until the player connects

Configure this per-product in your Pixlpay dashboard.

Setting Up Products

Example Commands

Configure products in your Pixlpay dashboard with commands like:

Product	Command
100 Coins	spawn Coins 100
Iron Sword	spawn SwordIron 1
Bronze Armor Set	spawn ArmorBronzeChest 1 spawn ArmorBronzeLegs 1 spawn HelmetBronze 1
50 Health Potions	spawn MeadHealthMajor 50
VIP Kit	spawn SwordBlackmetal 1 spawn ShieldBlackmetal 1 spawn Coins 500

Available Placeholders

Placeholder	Description
{player}	Player's Steam ID
{steam_id}	Player's Steam ID (alias)
{quantity}	Quantity purchased
{order_id}	Order ID
{order_number}	Order number
{product_name}	Product name
{customer_email}	Customer email
{customer_name}	Customer name

Common Item IDs

Weapons:

• SwordIron, SwordSilver, SwordBlackmetal
• AxeBlackMetal, AxeIron, AxeBronze
• BowHuntsman, BowDraugrFang
• AtgeirBronze, AtgeirIron, AtgeirBlackmetal

Armor:

• ArmorIronChest, ArmorIronLegs
• ArmorWolfChest, ArmorWolfLegs
• ArmorPaddedCuirass, ArmorPaddedGreaves
• CapeDeerHide, CapeWolf, CapeLox

Tools:

• Hammer, Hoe, Cultivator
• PickaxeIron, PickaxeBronze, PickaxeBlackMetal

Resources:

• Coins - In-game currency
• IronScrap, Iron, IronNails
• BlackMetal, BlackMetalScrap
• Crystal, DragonTear

Consumables:

• MeadHealthMajor, MeadHealthMedium, MeadHealthMinor
• MeadStaminaMajor, MeadStaminaMedium, MeadStaminaMinor
• SerpentStew, LoxMeatPie

TIP

For a complete list of Valheim item IDs, see the Valheim Wiki - Item IDs.

Important Notes

Spawn Behavior

Items spawned with the spawn command appear at a fixed location in the world (typically near spawn or the command executor). This is a limitation of Valheim's command system.

For best results:

• Use When Online execution mode so players are present when items spawn
• Consider creating custom pickup points where items spawn

Player Identification

Players are identified by their Steam ID (SteamID64). When customers purchase from your store, they should log in with Steam to link their account.

Server-Side Only

This plugin runs server-side only. Players do not need to install anything on their clients.

Troubleshooting

Commands Not Executing

1. Verify Server devcommands is installed in BepInEx/plugins/
2. Check the BepInEx log: BepInEx/LogOutput.log
3. Enable debug mode in config and check for errors
4. Ensure your Store Secret and Server Secret are correct

Players Not Being Detected

1. Player must be connected and fully loaded
2. Verify the correct Steam ID is being used in purchases
3. Check debug logs for player connection events

API Connection Issues

1. Ensure your server has internet access
2. Check firewall rules for outbound HTTPS (port 443)
3. Verify secrets in your configuration match the dashboard

Items Not Spawning

1. Verify Server devcommands is installed and working
2. Test the spawn command manually in-game
3. Check that the item ID is correct (case-sensitive)
4. Ensure the player is online if using "When Online" mode

Data Storage

The plugin stores data in BepInEx/config/PixlPay_data.json:

• Pending deliveries (for offline players)
• Command execution history (last 100 entries)

WARNING

This file is automatically managed - do not edit manually.

Log Files

Check BepInEx/LogOutput.log for plugin messages. Look for lines starting with [PixlPay].

Log Levels

Level	Description
[Info]	General information (startup, deliveries)
[Debug]	Verbose debug info (requires DebugMode = true)
[Warning]	Warnings (retries, connection issues)
[Error]	Errors (authentication failures, execution errors)

With debug mode enabled, you'll see detailed information about:

• API polling and response parsing
• Player connections and disconnections
• Command execution and results
• Delivery confirmations and failures
• Heartbeat status

Security Best Practices

1. Protect your config - Don't expose BepInEx/config/ publicly
2. Use unique Server Secrets - Each server should have its own secret
3. Keep BepInEx updated - Ensure you're running the latest version
4. Monitor logs - Check for unauthorized access attempts
5. Backup data - Keep copies of configuration files

Support

• Troubleshooting Guide
• Command Reference
• Discord Support
• Contact Support