🧩 PolyhydraGames Valheim REST Server

A modern replacement for RCON-based control of Valheim dedicated servers — exposing a full JSON REST API for in-game automation, integration, and remote management.

---

⚡ Overview

PolyhydraGames.Valheim.RestServer turns your Valheim dedicated server into a RESTful API host.
This allows local or remote tools (bots, dashboards, Twitch integrations, etc.) to trigger in-game actions via HTTP POST calls instead of legacy RCON commands.

Built for use with:

• PolyhydraGames’ automation ecosystem (SpottieBot, ChannelCheevos, etc.)
• Valheim mod developers wanting lightweight, stateless server integrations
• Streamers and admins managing events and server logic remotely

---

🌐 API

Base URL

http://<server-ip>:8080

All endpoints accept POST requests with JSON payloads.
A full OpenAPI spec and Postman collection are provided:

• 📘 OpenAPI Spec (YAML)
• 🧰 Postman Collection (JSON)

---

🧱 Example Endpoints

Action	Endpoint	Example Body
Shake Player Camera	POST /shake	json { "targetPlayer": "76561197962914477", "intensity": 5 }
Play Sound Near Player	POST /addnoise	json { "targetPlayer": "76561197962914477", "noise": "https://cdn.polyhydragames.com/audio/no.mp3", "position": { "x":10, "y":5, "z":3 } }
Spawn Entity	POST /spawn	json { "prefabName": "Troll", "count": 2, "position": { "x":0,"y":0,"z":0 } }
Teleport Player	POST /teleport	json { "targetPlayer": "76561197962914477", "position": { "x":100, "y":10, "z":50 } }
Apply Effect	POST /addeffect	json { "targetPlayer": "76561197962914477", "effectName": "SE_Rested" }
Send Server Message	POST /say	json { "message": "Server restarting in 5 minutes" }

---

📦 Installation

1. Requires:

   • BepInExPack for Valheim
   • Jötunn (Valheim Library)
   • HarmonyX

2. Install:

   • Extract the mod into your server’s BepInEx/plugins folder.
   • Restart your Valheim dedicated server.

3. Verify:

   • On startup, look for:

     [Info] PolyhydraGames REST API active on port 8080
     

   • Visit http://localhost:8080/info or curl http://localhost:8080/serverStats.

---

🧰 Integration Ideas

• Twitch / Channel Points
  Trigger /smite, /spawn, /shake, or /addeffect from Twitch redeems.
• OBS Overlay Widgets
  Display /serverStats and /time updates live on stream.
• Discord Bots
  Run /say or /ban from a Discord slash command.
• Automation Tools
  Use n8n, Node-RED, or Zapier webhooks to interact with your server via the REST API.

---

🧩 Schema Overview

Common object types (simplified):

{
  "Vector3": { "x": 0.0, "y": 0.0, "z": 0.0 },
  "PlayerRequest": { "targetPlayer": "SteamID64" },
  "AddNoiseRequest": { "targetPlayer": "SteamID64", "noise": "url", "position": "Vector3" },
  "SpawnArgs": { "prefabName": "string", "position": "Vector3", "count": 1, "level": 1 }
}

---

🔒 Security Notes

• The REST API is local by default — only accessible from the host machine.
  To expose it externally, bind it to your public IP and protect it with:
  • A reverse proxy (Nginx/Cloudflare)
  • API key headers or token middleware (coming soon)
• Avoid opening port 8080 publicly without access control.

---

🧰 Manifest Example

{
  "name": "PolyhydraGames_Valheim_RestServer",
  "version_number": "1.1.0",
  "website_url": "https://github.com/lancer1977/Valheim.RestServer",
  "description": "Exposes a RESTful API for Valheim server automation. JSON-based commands replace legacy RCON system.",
  "author": "PolyhydraGames",
  "dependencies": [
    "ValheimModding-Jotunn-2.26.1",
    "denikson-BepInExPack_Valheim-5.4.2102",
    "HarmonyX-2.10.1"
  ]
}

---

🧠 Developer Notes

All commands are implemented via Harmony patches and ZRoutedRpc actions. The REST bridge serializes incoming JSON into the same request DTOs used by the original RCON command handler (AddNoiseArgs, ShakeRequest, SpawnArgs, etc.).

Source: PolyhydraGames.Valheim.Core

---

🧾 License

MIT © 2025 PolyhydraGames