QUICK_REFERENCE.md

OpenVibe: Source Quick Reference

Key Paths

game/openvibe.games/                 Source mod folder
sdk/openvibe/                        Tracked OpenVibe C++ patch sources
engine/source-sdk-2013/              Local ignored Valve SDK checkout
backend/                             Fastify API
hammer/vmf/                          Editable VMF maps
game/openvibe.games/maps/            Compiled BSP maps
infra/                               Local and production infra templates
tools/                               Build, run, smoke, and map tools

Build

cd ~/src/openvibe-source/backend
npm run build
npm test

cd ~/src/openvibe-source
tools/build-sdk-linux.sh
tools/setup-openvibe-bin.sh

Run Locally

cd ~/src/openvibe-source
OPENVIBE_SRCDS_MAP_DELAY=3 tools/dev-up.sh

Stop:

cd ~/src/openvibe-source
tools/dev-down.sh

Smoke Tests

cd ~/src/openvibe-source
node tools/smoke-api.mjs
OPENVIBE_SRCDS_MAP_DELAY=3 OPENVIBE_SRCDS_SMOKE_TIMEOUT=45 tools/smoke-srcds.sh

Expected SRCDS output:

[srcds:hub] ok (ov_hub)
[srcds:prophunt] ok (ph_openvibe_dev)
[srcds:deathrun] ok (dr_openvibe_dev)
[srcds:fortwars] ok (fw_openvibe_dev)
[srcds:traitortown] ok (tt_openvibe_dev)

Maps

cd ~/src/openvibe-source
node tools/generate-dev-vmfs.mjs
tools/compile-dev-maps-wine.sh

Portal pads currently emit direct local connects for the Proton fallback:

connect 127.0.0.1:27015
connect 127.0.0.2:27016
connect 127.0.0.3:27017
connect 127.0.0.4:27018
connect 127.0.0.5:27019

Set OPENVIBE_USE_OV_JOIN=1 before regenerating VMFs to bake authenticated ov_join <mode> portal commands for a rebuilt custom client DLL.

Client / Server Commands

| Command | Side | Purpose |
| --- | --- | --- |
| ov_join <mode> | Client | Request travel token and connect to server. |
| ov_auth_steam | Client | Send Steam Web API ticket to backend auth. |
| openvibe_menu / ov_menu | Client | Open OpenVibe VGUI menu. |
| ov_open_url <url> | Client | Open OpenVibe web page in Steam/browser. |
| ov_prophunt_disguise <model> | Server | Apply allowlisted prop disguise. |
| ov_prophunt_reset_disguise | Server | Restore player model. |
| ov_fortwars_spawn <type> | Server | Spawn allowlisted build prop. |

API

curl -s http://127.0.0.1:3000/health | jq
curl -s http://127.0.0.1:3000/v1/servers | jq
curl -s http://127.0.0.1:3000/v1/assets/manifest | jq
curl -s http://127.0.0.1:3000/metrics

Travel request:

curl -s http://127.0.0.1:3000/v1/travel/request \
  -H 'Content-Type: application/json' \
  -d '{"steamId":"76561198000000000","mode":"prophunt"}' | jq

SRCDS Runtime

The working local Linux64 runtime is:

~/srcds/tf2

The installed Source SDK Base 2013 Dedicated Server directory in /mnt/6tb/... contains Windows server binaries in this environment, so it is not used for the Linux64 smoke tests.

Production Values

Set these before real deployment:

DATABASE_URL
SESSION_REDIS_URL
STEAM_WEB_API_KEY
STEAM_APP_ID
OPENVIBE_ADMIN_SECRET
OPENVIBE_CDN_BASE_URL

Backup

cd ~/src/openvibe-source
tools/backup-postgres.sh

Common Fixes

| Issue | Fix |
| --- | --- |
| API port still busy | tools/dev-down.sh, then check for leftover OpenVibe processes. |
| Server says map missing | Re-run tools/compile-dev-maps-wine.sh. |
| Game DLLs stale | Run tools/build-sdk-linux.sh then tools/setup-openvibe-bin.sh. |
| Hammer++ launch fails in Lutris | Use Steam non-game entry with Proton Experimental. |
| Steam auth returns 501 | Set STEAM_WEB_API_KEY and STEAM_APP_ID. |