openvibers/source.openvibe.games README.md

README.md

main 8.4 KB · 234 lines · markdown

1	# OpenVibe: Source
2
3	Linux-first Source SDK 2013 multiplayer project for OpenVibe: Source.
4
5	- Public identity: `OpenVibe.Games` — [openvibe.games](https://openvibe.games)
6	- Source mod folder: `game/openvibe.games`
7	- Backend/API: `backend/`
8	- Tracked OpenVibe C++ patch sources: `sdk/openvibe/`
9	- VScript game logic: `game/openvibe.games/scripts/vscripts/`
10	- Editable maps: `hammer/vmf/`
11	- Compiled maps: `game/openvibe.games/maps/`
12	- API bridge sidecar: `tools/ov-sidecar.mjs`
13
14	## Current State
15
16	Implemented and tested locally:
17
18	- Backend API - Fastify/TypeScript with dev auth, Steam Web API ticket auth, player profiles, shop, inventory, server registry, travel tokens, match rewards, leaderboard, admin shop management, CDN asset manifest, and optional Redis-backed sessions.
19	- Database - PostgreSQL migrations for players, inventory, shop, servers, join tokens, currency ledger, and match results.
20	- C++ GameDLL patch - tracked in `sdk/openvibe/` and applied into the local Valve SDK checkout with `tools/apply-openvibe-sdk.sh`.
21	- Authenticated travel - `ov_join <mode>` requests `/v1/travel/request`, stores a join token in userinfo, and connects to the selected server.
22	- Server-side arrival validation - the destination server validates join tokens with `/v1/travel/validate`.
23	- OpenVibe menu hooks - VGUI commands `openvibe_menu` / `ov_menu` plus `resource/GameMenu.res` expose OpenVibe hub actions instead of relying on the stock server browser.
24	- Prop Hunt C++ disguise command - `ov_prophunt_disguise <model>` swaps the player to an allowlisted prop model; `ov_prophunt_reset_disguise` restores the player model.
25	- Fort Wars C++ placement command - `ov_fortwars_spawn <crate\|barrel\|fence\|plate\|concrete>` spawns allowlisted physics props during the build phase.
26	- VScript game logic - Squirrel scripts for hub, Prop Hunt, Deathrun, Fort Wars, and Traitor Town prototypes.
27	- Portal maps - generated VMFs and compiled BSPs use direct local connects for the current Proton fallback; set `OPENVIBE_USE_OV_JOIN=1` when generating maps for a rebuilt custom client DLL.
28	- Sidecars - tail SRCDS logs and bridge `[OV]` events to the backend API.
29	- Production infra skeleton - Docker Compose, Docker Swarm stack, and Kubernetes manifests for API, PostgreSQL, Redis, and CDN/static assets.
30	- Hardening routes - party invites, capacity-aware party travel, moderation/audit events, Prometheus-style metrics, and backup tooling.
31
32	Verified locally on June 28, 2026:
33
34	- `backend`: TypeScript build passes.
35	- `backend`: 11 Vitest tests pass.
36	- Source SDK 2013 Linux64 build passes with the OpenVibe C++ patch applied.
37	- SRCDS smoke test passes for all five maps: `ov_hub`, `ph_openvibe_dev`, `dr_openvibe_dev`, `fw_openvibe_dev`, `tt_openvibe_dev`.
38	- Full dev stack registers all five servers and returns travel targets for hub, Prop Hunt, Deathrun, Fort Wars, and Traitor Town.
39
40	## Commands
41
42	\| Command \| Side \| Purpose \|
43	\| --- \| --- \| --- \|
44	\| `ov_join <mode>` \| Client \| Requests backend travel, stores join token, connects to target server. \|
45	\| `ov_auth_steam` \| Client \| Requests a Steam Web API ticket and posts it to `/v1/auth/steam`. \|
46	\| `openvibe_menu` / `ov_menu` \| Client \| Opens the OpenVibe VGUI hub menu. \|
47	\| `ov_open_url <url>` \| Client \| Opens OpenVibe web surfaces such as auth/inventory in Steam overlay/browser. \|
48	\| `ov_prophunt_disguise <model>` \| Server \| Applies allowlisted Prop Hunt disguise model. \|
49	\| `ov_prophunt_reset_disguise` \| Server \| Restores the normal player model. \|
50	\| `ov_fortwars_spawn <type>` \| Server \| Spawns allowlisted Fort Wars build props. \|
51
52	## Quick Start
53
54	### Backend
55
56	```bash
57	cd ~/src/openvibe-source/backend
58	npm install
59	npm run build
60	npm test
61	```
62
63	### Build Source SDK GameDLLs
64
65	```bash
66	cd ~/src/openvibe-source
67	tools/build-sdk-linux.sh
68	tools/setup-openvibe-bin.sh
69	```
70
71	`tools/build-sdk-linux.sh` applies `sdk/openvibe/` into `engine/source-sdk-2013/`, patches the VPC files, and builds the HL2MP client/server Linux64 game DLLs.
72
73	### Full Dev Stack
74
75	```bash
76	cd ~/src/openvibe-source
77	OPENVIBE_SRCDS_MAP_DELAY=3 tools/dev-up.sh
78	```
79
80	This starts:
81
82	- PostgreSQL
83	- OpenVibe API
84	- Hub SRCDS
85	- Prop Hunt SRCDS
86	- Deathrun SRCDS
87	- Fort Wars SRCDS
88	- Traitor Town SRCDS
89	- one sidecar per server
90
91	Stop everything:
92
93	```bash
94	cd ~/src/openvibe-source
95	tools/dev-down.sh
96	```
97
98	### Smoke Tests
99
100	```bash
101	cd ~/src/openvibe-source
102	node tools/smoke-api.mjs
103	OPENVIBE_SRCDS_MAP_DELAY=3 OPENVIBE_SRCDS_SMOKE_TIMEOUT=45 tools/smoke-srcds.sh
104	```
105
106	### Maps
107
108	```bash
109	cd ~/src/openvibe-source
110	node tools/generate-dev-vmfs.mjs
111	tools/compile-dev-maps-wine.sh
112	```
113
114	Hammer++ is currently launched as a non-Steam game with Proton Experimental. The repo also keeps direct Wine launchers:
115
116	```bash
117	tools/run-hammerpp.sh
118	tools/run-hammerpp-wined3d.sh
119	```
120
121	Recommended Hammer++ paths through Wine:
122
123	```text
124	Game directory:
125	Z:\home\workstation\src\openvibe-source\game\openvibe.games
126
127	VMF directory:
128	Z:\home\workstation\src\openvibe-source\hammer\vmf
129
130	Map output:
131	Z:\home\workstation\src\openvibe-source\game\openvibe.games\maps
132	```
133
134	## Dedicated Server Runtime
135
136	The installed Source SDK Base 2013 Dedicated Server path:
137
138	```text
139	/mnt/6tb/ssd_offload/home/workstation/.steam/debian-installation/steamapps/common/Source SDK Base 2013 Dedicated Server
140	```
141
142	contains Windows server binaries in this environment. The working local Linux64 runtime is the TF2 dedicated server install at:
143
144	```text
145	~/srcds/tf2
146	```
147
148	`tools/run-server.sh` defaults to `~/srcds/tf2` and uses the OpenVibe mod directory at `game/openvibe.games`.
149
150	## Architecture
151
152	```text
153	Source client
154	-> OpenVibe VGUI menu / launcher
155	-> Steam auth ticket or dev auth
156	-> OpenVibe.Games API
157	-> Hub SRCDS
158	-> portal pads
159	-> Minigame SRCDS shards
160
161	OpenVibe.Games API
162	-> PostgreSQL for durable game data
163	-> Redis for sessions when configured
164	-> CDN/static asset manifest for cosmetics
165	```
166
167	Gameplay remains Source-style authoritative SRCDS instances. The MMO-style part is the shared OpenVibe.Games account, inventory, currency, travel, and server orchestration layer.
168
169	Local Proton builds use direct portal connects so the maps work even when the Windows client DLL has not been rebuilt. The authenticated C++ travel path is still available by regenerating maps with `OPENVIBE_USE_OV_JOIN=1`.
170
171	## API Endpoints
172
173	\| Method \| Path \| Description \|
174	\| --- \| --- \| --- \|
175	\| `GET` \| `/health` \| Health check \|
176	\| `POST` \| `/v1/auth/dev` \| Local dev auth \|
177	\| `POST` \| `/v1/auth/steam` \| Steam Web API ticket auth \|
178	\| `GET` \| `/v1/me?steamId=` \| Player profile + inventory + shop \|
179	\| `GET` \| `/v1/shop` \| Shop catalog \|
180	\| `GET` \| `/v1/assets/manifest` \| CDN-backed cosmetic asset manifest \|
181	\| `POST` \| `/v1/shop/buy` \| Purchase item \|
182	\| `POST` \| `/v1/equip` \| Equip owned item \|
183	\| `GET` \| `/v1/leaderboard` \| Top players by XP \|
184	\| `POST` \| `/v1/servers/register` \| Register game server \|
185	\| `POST` \| `/v1/servers/heartbeat` \| Update server status \|
186	\| `GET` \| `/v1/servers` \| List live servers \|
187	\| `POST` \| `/v1/travel/request` \| Reserve travel token \|
188	\| `POST` \| `/v1/travel/validate` \| Consume travel token \|
189	\| `POST` \| `/v1/parties` \| Create party \|
190	\| `GET` \| `/v1/parties?partyId=` \| Get party members \|
191	\| `POST` \| `/v1/parties/invite` \| Invite friend to party \|
192	\| `POST` \| `/v1/parties/invite/accept` \| Accept party invite \|
193	\| `POST` \| `/v1/parties/travel` \| Reserve one server for the whole party \|
194	\| `POST` \| `/v1/matches/end` \| Record match result + reward \|
195	\| `POST` \| `/v1/admin/shop/items` \| Admin: upsert shop item \|
196	\| `POST` \| `/v1/admin/audit/events` \| Admin: record moderation/audit event \|
197	\| `GET` \| `/v1/admin/audit/events` \| Admin: list audit events \|
198	\| `GET` \| `/metrics` \| Prometheus-style service metrics \|
199
200	## Production Configuration
201
202	Production auth requires:
203
204	- `STEAM_WEB_API_KEY`
205	- `STEAM_APP_ID`
206	- `OPENVIBE_ADMIN_SECRET`
207	- `DATABASE_URL`
208	- `SESSION_REDIS_URL`
209	- `OPENVIBE_CDN_BASE_URL`
210
211	Infrastructure templates live in:
212
213	- `infra/docker-compose.yml`
214	- `infra/production/docker-stack.yml`
215	- `infra/kubernetes/openvibe.yaml`
216	- `infra/cdn/nginx.conf`
217
218	Local database backups:
219
220	```bash
221	cd ~/src/openvibe-source
222	tools/backup-postgres.sh
223	```
224
225	## Remaining Work
226
227	The foundation is running. The next real work is content and hardening:
228
229	- Replace dev models/trails with real OpenVibe cosmetic assets.
230	- Add real hosted CDN storage behind `openvibe.games`.
231	- Wire Steam production credentials and app identity.
232	- Expand Prop Hunt, Deathrun, Fort Wars, and Traitor Town into full game rules.
233	- Add full admin web views, alert routing, and deployment secrets management.
234