https://github.com/trevorftp/nimbus
A server proxy built for Vintagestory Servers
https://github.com/trevorftp/nimbus
nimbus server-proxy stratum vintagestory
Last synced: about 1 month ago
JSON representation
A server proxy built for Vintagestory Servers
- Host: GitHub
- URL: https://github.com/trevorftp/nimbus
- Owner: trevorftp
- License: other
- Created: 2026-05-25T16:29:46.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2026-05-25T18:39:12.000Z (about 2 months ago)
- Last Synced: 2026-05-25T19:27:35.015Z (about 2 months ago)
- Topics: nimbus, server-proxy, stratum, vintagestory
- Language: C#
- Homepage: https://discord.gg/pd24fawhsD
- Size: 49.8 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Nimbus
[](https://discord.gg/pd24fawhsD)
[](https://github.com/trevorftp/Nimbus/stargazers)
[](https://github.com/trevorftp/Nimbus/issues)
[](https://github.com/trevorftp/Nimbus/commits)
[](LICENSE)
A [Velocity](https://papermc.io/software/velocity)-style proxy for [Vintage Story](https://www.vintagestory.at/).
Put many backends behind one address, move players between them on demand, and present the whole thing as a single entry on the server list. The transfer is a quick disconnect/reconnect to the next backend; the vanilla protocol doesn't give us a soft-respawn, so a Velocity-grade seamless swap isn't on the table. Everything else is.
## How it fits together
- **Registry** — small ASP.NET Core service. Backends heartbeat in. Mints short-lived reservations so a player can land on a specific backend without re-running auth.
- **Proxy** — TCP/UDP relay. Fronts every backend on one address. Health-aware routing, drain, swap, redirect, disconnect-transfer. Forwards the real client IP to the backend over the reservation.
- **`nimctl`** — CLI for the proxy's admin socket. List sessions, swap a player, drain a backend.
The registry can also advertise the whole network as one entry on the public VS server list, with aggregated player count and required mods pulled from live backends.
## Building
Requires the .NET 10 SDK.
```powershell
dotnet build Nimbus.slnx -c Release
```
## Running
```powershell
cd Nimbus.Registry; dotnet run -c Release
cd Nimbus.Proxy; dotnet run -c Release
```
First run writes a config next to each binary. Change the `SharedSecret` before exposing anything.
## Backend integration
Backends need to do two things:
1. Heartbeat to the registry (`BackendHeartbeat` in `Nimbus.Shared`).
2. On login, ask the registry to consume a reservation for the joining player and accept the join if it matches.
`Nimbus.Shared` carries the DTOs and the HMAC signer; you don't have to reimplement either. Every registry request needs the four `X-Nimbus-*` headers.
There is no drop-in mod for stock servers yet. Nimbus runs against a private fork; a public integration layer is on the list.
## Caveats
- The vanilla client has a bug in `ClientMain.ExitAndSwitchServer` that crashes the next session after a redirect. Until upstream patches it, clients need [RedirectFix](https://github.com/trevorftp/redirectfix). It auto-installs from the backend's required-mods list on first join, so for players this is transparent.
- One player per source IP for UDP (NAT'd LAN parties not supported yet).
## Discord
Questions, bug reports, design arguments: [discord.gg/pd24fawhsD](https://discord.gg/pd24fawhsD).
## License
See [LICENSE](LICENSE). Source-available, no resale, no rebrand-and-redistribute.
Nimbus is an unofficial third-party project. Not affiliated with or endorsed by Anego Studios. "Vintage Story" is a trademark of Anego Studios. See [NOTICE](NOTICE) for the full attribution.