process-communist-server

Companion compute server for the ProcessCommunist Minecraft Forge 1.20.1 mod.
Run this on a secondary machine on your LAN (e.g. Raspberry Pi) to offload expensive server computations.

Quick start

# On the secondary machine (Pi, spare laptop, …)
npx process-communist-server

# With custom host/port
npx process-communist-server --host 0.0.0.0 --port 1248

Or install globally and run as a daemon:

npm install -g process-communist-server
process-communist-server

What it does

The server exposes four task endpoints that the Forge mod calls asynchronously:

| Endpoint | Task | |---|---| | POST /task/chunkgen | Simplex-noise fBm height-map for a 16×16 chunk | | POST /task/pathfinding | 3-D A* pathfinding with blocked-voxel input | | POST /task/plantgrowth | Probabilistic crop/plant growth stage decision | | POST /task/fluid | Cellular-automaton fluid spread (water / lava) |

All tasks return a JSON response immediately. The Forge mod applies the results on the next server tick and falls back to vanilla Minecraft if the server is unreachable or exceeds the configured timeout.

API reference

GET /ping

Health check. Returns { pong: true, ts: <epoch ms> }.

GET /info

Server metadata.

POST /task/chunkgen

{ "seed": 123456789, "chunkX": 0, "chunkZ": 0 }

Returns: { "heights": [63, 64, 65, ...] } (256 integers, x*16+z indexed)

POST /task/pathfinding

{
  "sx": 10, "sy": 64, "sz": 20,
  "gx": 15, "gy": 64, "gz": 25,
  "blocked": [[1,0,0], [0,0,1]]
}

Returns: { "path": [[10,64,20], [11,64,20], ...] }

POST /task/plantgrowth

{
  "blockId": "minecraft:wheat",
  "growthStage": 3,
  "lightLevel": 14,
  "moisture": 7
}

Returns: { "newStage": 4 } or { "newStage": -1 } (no growth this tick)

POST /task/fluid

{
  "fluid": "water",
  "ox": 5, "oy": 64, "oz": 5,
  "neighbours": [[5,63,5,-1],[4,64,5,3],[6,64,5,-1],[5,64,4,-1],[5,64,6,-1]]
}

Returns: { "updates": [[5,63,5,8],[6,64,5,7]] } (each entry: [x,y,z,level], level -1 = remove)

Environment variables

| Variable | Default | Description | |---|---|---| | PC_PORT | 1248 | Port to listen on | | PC_HOST | 0.0.0.0 | Host to bind to |

Raspberry Pi setup example

# Install Node.js 18+ on Pi (if not already)
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

# Run the server (auto-start on boot with PM2)
npm install -g pm2 process-communist-server
pm2 start process-communist-server
pm2 startup
pm2 save

Then set secondaryUnitIp in processcommunist-common.toml to your Pi's LAN IP.

Notes

• All computations run in the V8 JS engine — fast, deterministic, no native deps.
• The fluid and growth algorithms intentionally approximate Minecraft's vanilla logic; exact parity would require JVM access.
• Tasks are stateless — no world state is stored between requests.
• The mod never blocks the server thread; all delegation is async with configurable timeout fallback.