feat: add optional Glitch WebGL deployment

[ProdigyView]

Summary

• add optional Glitch runtime integration, secret-injection scripts, and WebGL packaging/deployment docs
• make hosted WebGL playable via browser WebSocket transport with a WebGL-safe JSON NetCodec envelope
• add opt-in PostgreSQL persistence while keeping SQLite as the default backend
• document the deployed Glitch/Azure hosted WebGL path and link Glitch + itch.io from the README

Verification

• deployed Azure Container Apps server image bbstarsacr0628222440.azurecr.io/bbstars-server:webgl-20260629055312
• deployed Glitch WebGL build a223085e-558f-4c2a-9b6f-d024a3b1aeec (ready)
• local WebGL smoke: browser joined as WebGLClean, cached content, and rendered the ship/world
• BBS_POSTGRES_TEST_CONNECTION_STRING=... dotnet test tests/BlocksBeyondTheStars.Tests/BlocksBeyondTheStars.Tests.csproj --filter 'PostgreSqlRepositoryTests|WebSocketTransportTests' -v minimal
• dotnet build BlocksBeyondTheStars.CI.slnf --no-incremental -v minimal
• dotnet format BlocksBeyondTheStars.CI.slnf --verify-no-changes
• git diff --check

Notes

• Glitch install/deploy tokens are not committed; the generated Unity secrets partial is git-ignored and cleared after builds.
• Plain dotnet test on macOS still hits the existing Windows-only launcher targeting issue; the CI solution filter remains the cross-platform path.

[CLAassistant]

All committers have signed the CLA.

[ProdigyView]

Follow-up deployed and verified on 2026-06-29.

• Fixed WebGL menu/Codex close handling: Esc/Tab now close the in-game menu/browser panes before the app shell can open the leave-game prompt.
• Enabled free space flight by default and added hosted env overrides, including BBS_FREE_FLIGHT=true for the Azure Container App.
• Azure Container App is on image bbstarsacr0628222440.azurecr.io/bbstars-server:webgl-20260629070734, revision bbstars-web--0000002, healthy on /healthz.
• Glitch WebGL deployment a223218b-c7dd-44e7-8ca7-37eac3d5d362 is ready.
• Verification: focused ServerConfig/WorldOptions tests passed; local WebGL dry-run build passed; production WebGL build/upload passed; dotnet build BlocksBeyondTheStars.CI.slnf --no-incremental passed with 0 warnings; dotnet format --verify-no-changes passed; secret scan found no committed Glitch tokens.

[marceld23]

Hi @ProdigyView — this is fantastic, thank you so much! 🎉 Web support is something we've really wanted, and the fact that you not only built it but got it live and playable in a browser is genuinely exciting — that's exactly the kind of thing that helps more people discover the project. Huge appreciation for the work here (WebGL transport, optional Postgres backend, deployment tooling, docs — that's a lot!).

We'd love to get this in. A few things to sort out together, grouped by priority:

🔴 Need before merge

1. The WebGL JS bridge seems to be missing. BrowserWebSocketClientTransport imports BbsWsConnect / BbsWsSendBase64 / BbsWsDisconnect via [DllImport("__Internal")], and the docs reference client/Assets/Plugins/BbsWebSocket.jslib, but that .jslib isn't in the PR (or anywhere in the repo). I'm guessing it exists on your machine and just didn't get committed — could you add it? Without it the IL2CPP WebGL build can't link. 🙂
2. Small link.xml typo — it preserves BlocksBeyondTheStars.Client.Core, but the runtime assembly is BlocksBeyondTheStars.Client, so the entry is currently a no-op and doesn't protect the client assembly from stripping.
3. CLA — the bot will need your signature before it can merge.

🟠 Two networking things worth tightening

4. Silent message loss to browsers — NetCodec.ConvertToJsonPayload falls back to returning raw MessagePack bytes on a decode miss, and those get sent to a JSON-only browser client, which drops them silently. Could we log + drop instead of ever sending binary to a browser socket?
5. Frame-size guard — the WS receive loop accumulates an unbounded buffer per message and DecodeJson has no size/depth cap, so a misbehaving client could OOM the server. A max-frame-size limit would close that off.

🟢 The Glitch deployment — let's take it further together!

Honestly, we love that you published it — getting the game in front of people is exactly the goal. 🙌 Please absolutely keep hosting it on Glitch if you'd like — we're not looking to take your deployment or account away at all. The only ask is that you mark it clearly as a fork / unofficial build so players can tell it apart from an official release.

On our side, we'd also like to set up the project's own Glitch account so we can wire the WebGL build straight into our CI/CD and keep an official web version maintained, versioned, and in sync with releases. Since it's a game aimed at kids, having an official channel under our control also helps us keep an eye on the privacy/branding side. So think of it as two builds living side by side — yours as a community preview, ours as the release channel.

Concretely, that'd mean:

• Keep your Glitch deployment running as an unofficial/fork preview (just labelled as such), and
• Split the Glitch-specific deploy tooling + README links into a separate PR, so the reusable WebGL/browser transport can land cleanly here. Happy to help with that split.
• For the in-repo client, keep the Glitch SDK fully optional / off by default (it already is — nice!), and move the hardcoded defaults (api.glitch.fun, the default title id) behind env vars so anyone can point it at their own account.

If you're up for it, we'd genuinely welcome your input on the CI/CD deploy setup too — you clearly know this platform well!

✨ Things that are already great

• The Postgres port is clean — full IWorldRepository parity, properly parameterized (no injection), and SQLite correctly stays the default. This could even land first as its own PR. (Tiny note: CreateBackup writes a JSON snapshot with no restore path, unlike the openable SQLite .db — worth documenting as snapshot-only.)
• No secrets/tokens/connection strings are committed, the generated secrets partial is git-ignored, and the integration is dormant by default — really well handled. (One small thing: the ACR registry name bbstarsacr0628222440.azurecr.io slipped into TODO.md / GLITCH_INTEGRATION.md — worth scrubbing.)

A nice path forward

Maybe 2–3 smaller PRs: (1) Postgres backend, (2) WebGL/browser transport + the missing .jslib, (3) Glitch deployment for discussion. The first two we can move on fast.

Thanks again — this is a brilliant contribution and a direction we're really happy about. 🚀

[ProdigyView]

Addressed the merge-blocking review items in a rewritten single-commit branch:

• added/tracked client/Assets/Plugins/BbsWebSocket.jslib + .meta;
• fixed link.xml to preserve BlocksBeyondTheStars.Client;
• changed browser payload conversion to log/drop malformed server payloads instead of sending raw MessagePack;
• added WebSocket frame-size guard plus JSON payload size/depth caps;
• made the WebSocket test avoid cancellation-aborting the client socket and added drop/oversize tests;
• removed Glitch deployment scripts/README links and scrubbed hosted deployment IDs/ACR defaults from this PR;
• kept the optional Glitch runtime hook dormant, with no committed API/title defaults;
• documented PostgreSQL JSON backups as snapshot-only/no built-in restore importer.

Verification: full server/shared tests passed (789 tests); client-core tests passed (96 tests); CI solution build with -warnaserror passed with 0 warnings; dotnet format --verify-no-changes passed; Unity WebGL build succeeded; secret/deployment-id scan is clean.

GitHub currently shows CLA passing on the rewritten commit; the PR is now waiting on review.

[ProdigyView]

Just a note; with the web hosted version, it might be best for the players experience to remove hosting and other options, and just have them automatically login to the set server. Less questions users have, the better.

[marceld23]

Awesome work, @ProdigyView — you turned this around fast and nailed pretty much everything. 🙌 I went through the updated branch and confirmed:

• ✅ BbsWebSocket.jslib (+ .meta) is in now, with the real mergeInto bridge
• ✅ browser payload conversion logs/drops instead of sending raw MessagePack
• ✅ WebSocket frame-size guard + JSON depth/size caps (with the new drop/oversize tests)
• ✅ Glitch deploy scripts + README links removed, ACR/title IDs scrubbed, runtime hook dormant with no committed defaults
• ✅ Postgres backup documented as snapshot-only
• ✅ CLA signed

Just one tiny nit left and then I think we're there: in link.xml, the old BlocksBeyondTheStars.Client.Core line is still there alongside the correct BlocksBeyondTheStars.Client one. Client.Core isn't a real assembly, so it's a harmless no-op — just worth removing to avoid confusion.

The FreeSpaceFlight default change is fine by us — happy to keep it. 👍

On your auto-login note — really good instinct, and you already gave us the building block (the bbs_auto_join URL param). Trimming the WebGL menu down to a one-click "just play" experience is something we'd love to do, but we'll handle that as a follow-up so this PR stays focused. Same for the hosted deployment/CI — we'll set that up on our side under the project's own account, exactly as we discussed.

Thank you again — this is genuinely great, and we're excited to get web play into the project. 🚀

[marceld23]

Awesome work, @ProdigyView — you turned this around fast and nailed pretty much everything. 🙌 I went through the updated branch and confirmed:

• ✅ BbsWebSocket.jslib (+ .meta) is in now, with the real mergeInto bridge
• ✅ browser payload conversion logs/drops instead of sending raw MessagePack
• ✅ WebSocket frame-size guard + JSON depth/size caps (with the new drop/oversize tests)
• ✅ Glitch deploy scripts + README links removed, ACR/title IDs scrubbed, runtime hook dormant with no committed defaults
• ✅ Postgres backup documented as snapshot-only
• ✅ CLA signed, and CI is green across the board

There was one tiny leftover in link.xml — the old BlocksBeyondTheStars.Client.Core line (not a real assembly, so a harmless no-op) sitting next to the correct BlocksBeyondTheStars.Client one. Don't worry about it — we'll tidy that one up on our side. Nothing for you to do.

The FreeSpaceFlight default change is fine by us — happy to keep it. 👍

On your auto-login note — really good instinct, and you already gave us the building block (the bbs_auto_join URL param). Trimming the WebGL menu down to a one-click "just play" experience is something we'd love to do, but we'll handle that as a follow-up so this PR stays focused. Same for the hosted deployment/CI — we'll set that up on our side under the project's own account, exactly as we discussed.

Merging now — thank you again, this is a brilliant contribution and we're genuinely excited to have web play in the project. 🚀

[marceld23]

Quick follow-up for visibility, @ProdigyView — we'''ve opened two tracking issues for the next steps building on your work here:

• WebGL: simplify the browser start menu (one-screen name + Play) #120 — WebGL: simplify the browser start menu (one-screen name + Play). ✅ Already done in feat(webgl): slim browser start menu to name + Play #122.
• WebGL: serve the browser client from the Docker image (play in-browser, self-hosted) #121 — WebGL: serve the browser client from the Docker image (play in-browser, self-hosted). Analysis done, implementation planned.

Thanks again for getting browser play off the ground — it'''s the foundation both of these build on. 🚀