Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

feat(club): open /stripclub as a second entrance on a brick back alley

ni3ab80bda885b74
diff --git a/.gitignore b/.gitignore
index dacdf6a78..fdc15b183 100644
--- a/.gitignore
+++ b/.gitignore
@@ -304,6 +304,8 @@ scripts/.corr-*
/club.mp3
/alleyway.glb
/tour.glb
+/environment_ally_with_barstrip_club.glb
+/back-alley-source.glb
# Root-level scratch/debug artifacts (one-off agent probe scripts + screenshots).
# Anchored to root so legitimate underscore-prefixed files elsewhere are unaffected.
diff --git a/STRUCTURE.md b/STRUCTURE.md
index aafefd1cb..0e84bbe55 100644
--- a/STRUCTURE.md
+++ b/STRUCTURE.md
@@ -89,7 +89,7 @@ bottom.
| x402 Preflight (signed payability attestations) | Format core [api/_lib/x402/preflight.js](api/_lib/x402/preflight.js), server [api/x402/preflight.js](api/x402/preflight.js) `→ /.well-known/x402-preflight`, page [pages/preflight.html](pages/preflight.html) `→ /preflight` + [src/preflight-page.js](src/preflight-page.js), client SDK + CLI [packages/x402-preflight](packages/x402-preflight), MCP tool [api/_mcp3d/tools/preflight.js](api/_mcp3d/tools/preflight.js), spec [specs/x402-preflight.md](specs/x402-preflight.md), docs [docs/x402-preflight.md](docs/x402-preflight.md) | Live | The reliability layer x402 is missing. x402 says what a resource costs; nothing says whether the seller can still SETTLE it, so a buyer discovers an empty seller fee wallet only after signing. Born from the 2026-08-28 incident where three.ws was that seller: sponsor at 0.000899107 SOL against a 0.02 floor, 95 payment attempts, 0 settled, 3 hours. A seller publishes a signed, time-bounded ed25519 attestation of per-network payability, built from the same `gatherX402SettleHealth()` sensor healthz uses plus the live sponsor floor guard, so every field is measured rather than declared. `payable` is three-valued (a seller that cannot measure must say `unknown`, never `true`), every rate ships with its window and sample, `alternates` names the rails that DO work so a client re-routes in the same round trip, and `retry_after` stops a fleet synchronising into a retry storm. Verification enforces expiry, so a healthy attestation cannot be replayed through an outage. The open format is unencumbered: any x402 seller can serve one, any client can verify one, nothing routes through three.ws. Tests: [tests/x402-preflight.test.js](tests/x402-preflight.test.js) (38, including a cross-implementation digest check that the browser SDK and the node server sign byte-identical bytes). |
| Paid Market Data API (x402, 17 endpoints) | Registry [api/_lib/market-data/registry.js](api/_lib/market-data/registry.js), fetchers [api/_lib/market-data/fetch.js](api/_lib/market-data/fetch.js), factory [api/_lib/market-data/endpoint.js](api/_lib/market-data/endpoint.js), routes `api/x402/market-*.js` `→ /api/x402/market-<category>`, free index [api/x402/market.js](api/x402/market.js) `→ /api/x402/market`, catalog projection [api/_lib/service-catalog/services/market-data.js](api/_lib/service-catalog/services/market-data.js), docs [docs/market-data-api.md](docs/market-data-api.md) `→ /docs/market-data-api` | Live | Every free /markets feed (coins, coin profile, price history, categories, exchanges, derivatives, global+Fear&Greed, ETH gas, trending, DeFi TVL, chains, ~15k yield pools, stablecoins, fees/revenue, DEX volumes, hacks) wrapped as pay-per-call x402 endpoints at $0.001 USDC (Solana/Base), plus the $0.005 one-call `market-pulse` bundle. One registry drives the live 402s, the discovery-doc listings, and the free index — zero drift by construction; the fetchers delegate to the SAME exported builders the free pages use (`api/coin/*`, `api/defi/*`), so paid data always matches the site. Params rejected pre-settle (422) and upstream outages (503) never charge the buyer. Tests: [tests/market-data-api.test.js](tests/market-data-api.test.js). |
| Datapoint fabric (x402, 480k+ endpoints) | Registry [api/_lib/market-data/datapoints.js](api/_lib/market-data/datapoints.js), dynamic route [api/x402/d/[...path].js](api/x402/d/%5B...path%5D.js) `→ /api/x402/d/<family>/<id>/<metric>`, free catalog [api/x402/d/index.js](api/x402/d/index.js) `→ /api/x402/d`, discovery slice `buildDatapointItems` in [api/wk.js](api/wk.js), docs § in [docs/market-data-api.md](docs/market-data-api.md#the-datapoint-fabric--480000-standalone-endpoints) | Live | Every individual market datapoint as its OWN standalone paid endpoint — one URL = one value = one $0.0005 USDC x402 micro-payment (override `X402_PRICE_DATAPOINT_<FAMILY>`). 9 families × 68 metrics × live id spaces ≈ 484k addressable endpoints (~17.5k coins × 20, ~15.5k pools × 7, ~6k protocols × 6, chains, stablecoins, exchanges, global/gas/fear-greed) served by ONE dynamic route reading the registry; ids are runtime values, nothing hardcodes a third-party asset. Path that cannot exist → 404/422 with NO 402 issued; unknown id/outage rejects pre-settle. Free catalog enumerates families, metrics, prices, and pages each family's full live id space (200/page) so crawlers can walk the universe; the .well-known discovery doc carries a curated runtime-derived slice (~83 concrete resources). Tests: [tests/market-datapoints.test.js](tests/market-datapoints.test.js). |
-| Pole Club (x402 micro-tips drive a live 3D room) | Page [pages/club.html](pages/club.html) `→ /club`, stage app [src/club.js](src/club.js) with [src/club-camera.js](src/club-camera.js), [src/club-crowd.js](src/club-crowd.js), [src/club-dances.js](src/club-dances.js), [src/club-audio.js](src/club-audio.js), [src/club-venue.js](src/club-venue.js), [src/club-perf.js](src/club-perf.js), [src/club-sequence.js](src/club-sequence.js); walk-in [src/club-entrance.js](src/club-entrance.js) + cover gate [src/club-gate.js](src/club-gate.js) (shared express flag [src/shared/club-express.js](src/shared/club-express.js)), the 3D doorman [src/club-bouncer.js](src/club-bouncer.js) and the line outside [src/club-queue.js](src/club-queue.js); paid endpoints [api/x402/club-cover.js](api/x402/club-cover.js) `→ /api/x402/club-cover` and [api/x402/dance-tip.js](api/x402/dance-tip.js) `→ /api/x402/dance-tip`; free reads [api/club/leaderboard.js](api/club/leaderboard.js), [api/club/tips.js](api/club/tips.js), [api/club/tips-stream.js](api/club/tips-stream.js) `→ /api/club/tips/stream` (SSE), [api/club/presence.js](api/club/presence.js); payouts [api/\_lib/club/payouts.js](api/_lib/club/payouts.js) via the `/api/cron/club-payouts` job; assets [public/club/](public/club) | Live | The platform's showcase of x402 as a live interaction loop rather than a billing detail: a $0.01 USDC cover charge at the door (with an on-chain bouncer that reads the paying wallet's ban list and prior visits, and a device-cached pass so one cover lasts the night). That bouncer is also a character in the alley: a rigged avatar posted beside the door who tracks you as you walk up, quotes the cover, and acts out each step of the payment (reads the list while the wallet is checked, nods you through by tier, shakes his head on a refusal), driven by the `club:door-state` event the cover gate emits on every state change; tap him and he explains how the club works. A roped line of waiting avatars talks among itself beside him, then $0.001 USDC per routine at three poles. A settled tip is what puts a dancer on the pole, so the payment IS the interaction. Third-person walk-in through alley → gallery → clubhouse → stage before the room opens; dancers are ordinary gallery avatars retargeted onto the shared clip library, swappable per pole. Tips land live over SSE with REST backfill on reconnect, and per-dancer earnings accrue to `club_dancer_wallets` for the payout sweep. `/club?demo` is the express entry that skips the cover for QA and recordings. |
+| Pole Club (x402 micro-tips drive a live 3D room) | Page [pages/club.html](pages/club.html) `→ /club` and `→ /stripclub` (same page, the path picks the walk-in via [src/club-variant.js](src/club-variant.js)), stage app [src/club.js](src/club.js) with [src/club-camera.js](src/club-camera.js), [src/club-crowd.js](src/club-crowd.js), [src/club-dances.js](src/club-dances.js), [src/club-audio.js](src/club-audio.js), [src/club-venue.js](src/club-venue.js), [src/club-perf.js](src/club-perf.js), [src/club-sequence.js](src/club-sequence.js); walk-in [src/club-entrance.js](src/club-entrance.js) + cover gate [src/club-gate.js](src/club-gate.js) (shared express flag [src/shared/club-express.js](src/shared/club-express.js)), the 3D doorman [src/club-bouncer.js](src/club-bouncer.js) and the line outside [src/club-queue.js](src/club-queue.js); paid endpoints [api/x402/club-cover.js](api/x402/club-cover.js) `→ /api/x402/club-cover` and [api/x402/dance-tip.js](api/x402/dance-tip.js) `→ /api/x402/dance-tip`; free reads [api/club/leaderboard.js](api/club/leaderboard.js), [api/club/tips.js](api/club/tips.js), [api/club/tips-stream.js](api/club/tips-stream.js) `→ /api/club/tips/stream` (SSE), [api/club/presence.js](api/club/presence.js); payouts [api/\_lib/club/payouts.js](api/_lib/club/payouts.js) via the `/api/cron/club-payouts` job; assets [public/club/](public/club) | Live | The platform's showcase of x402 as a live interaction loop rather than a billing detail: a $0.01 USDC cover charge at the door (with an on-chain bouncer that reads the paying wallet's ban list and prior visits, and a device-cached pass so one cover lasts the night). That bouncer is also a character in the alley: a rigged avatar posted beside the door who tracks you as you walk up, quotes the cover, and acts out each step of the payment (reads the list while the wallet is checked, nods you through by tier, shakes his head on a refusal), driven by the `club:door-state` event the cover gate emits on every state change; tap him and he explains how the club works. A roped line of waiting avatars talks among itself beside him, then $0.001 USDC per routine at three poles. A settled tip is what puts a dancer on the pole, so the payment IS the interaction. Third-person walk-in through alley → gallery → clubhouse → stage before the room opens; dancers are ordinary gallery avatars retargeted onto the shared clip library, swappable per pole. Tips land live over SSE with REST backfill on reconnect, and per-dancer earnings accrue to `club_dancer_wallets` for the payout sweep. `/club?demo` is the express entry that skips the cover for QA and recordings. `/stripclub` is a second entrance to the same room: it opens on a brick back alley (CC BY 4.0 model, credited on screen and in [public/club/venue/LICENSES.md](public/club/venue/LICENSES.md)) instead of the neon alley, shares the cover pass, and falls back to the neon alley if its model cannot load. |
| Living Stages (an AI host performs live, tipped in $THREE) | Page [pages/stage.html](pages/stage.html) `→ /stage` (the marquee) and `→ /stage?id=<stage>` (the venue), runtime [src/stage.js](src/stage.js), realtime client [src/stage-net.js](src/stage-net.js) → `stage_world` in [multiplayer/src/rooms/StageRoom.js](multiplayer/src/rooms/StageRoom.js) with the show logic in [multiplayer/src/stage-show.js](multiplayer/src/stage-show.js); API [api/stage/index.js](api/stage/index.js) `→ /api/stage`, tips [api/stage/tip.js](api/stage/tip.js) `→ /api/stage/tip`, host brain [api/stage/host.js](api/stage/host.js) `→ /api/stage/host` (HMAC, multiplayer server only) | Live | An embodied agent hosts a show in a 3D venue. Each beat is a timed `utterance` broadcast every client renders identically: TTS through a `PositionalAudio` whose analyser drives lip-sync, plus live captions, so a late joiner or a no-WebGL browser still reads the show. The crowd is co-present on a server-assigned ring, questions queue for the host, and a $THREE tip that settles on-chain to the host wallet is verified by the API and pushed into the room so the host reacts within a beat. The page resolves the realtime server through the same chain as `/play` ([src/shared/game-server-url.js](src/shared/game-server-url.js)) from the `game-server` meta it carries; localhost talks to `:2567`. The client subscribes to the host frame with `listen` (the join resolves before the first state patch, so `onChange` on the not-yet-decoded child throws) and registers message handlers before any state work, because the room opens the show the instant the first person arrives. With no feed the pill reads offline and reconnects on tap. Docs: [docs/stage.md](docs/stage.md). Tests: [tests/multiplayer-server-boot.test.js](tests/multiplayer-server-boot.test.js) (a real `stage_world` join wired the way the page does it), [tests/stage-show.test.js](tests/stage-show.test.js) |
| Fits: the public cosmetics economy | [pages/fits.html](pages/fits.html) `→ /fits`, page module [src/fits.js](src/fits.js) + pure helpers [src/fits-lib.js](src/fits-lib.js), backends [api/cosmetics/leaderboard.js](api/cosmetics/leaderboard.js) + [api/cosmetics/earnings.js](api/cosmetics/earnings.js), engine [api/_lib/cosmetics-economy.js](api/_lib/cosmetics-economy.js) | Live | The settled-sale cosmetics ledger, promoted out of a panel inside `/play` into a public surface. Rarest premium fits ranked by how few wallets own them (owner count first, rarity as the tie-break, so a legendary never sorts under an equally-scarce rare), top collectors by rarity-weighted flex score, top creators by **actually settled** USDC, and a live sales drip; each fit deep-links to its coin world at `/play?coin=<mint>`. Plus a creator-earnings lookup any wallet can run without an account (lifetime + 30-day, paid vs pending, per-cosmetic and per-coin-world breakdowns), reachable in one click from each creator row rather than by copy-pasting an address. Coin mints are runtime ledger values, never hardcoded. Headline numbers are derived from the same rows rendered beneath them, so they cannot disagree; the volume tile is labelled as the returned sales window, not as an all-time total. Sub-cent sales keep their precision instead of collapsing to $0.00. Tests: [tests/fits-lib.test.js](tests/fits-lib.test.js) |
| Receipt Vault: buyer-side proof of purchase | [pages/receipts.html](pages/receipts.html) `→ /receipts`, page module [src/receipts.js](src/receipts.js) + pure helpers [src/receipts-lib.js](src/receipts-lib.js), backend [api/x402/my-receipts.js](api/x402/my-receipts.js), storage [api/_lib/x402/receipt-storage.js](api/_lib/x402/receipt-storage.js), issuer [api/_lib/x402/offer-receipt-issuer.js](api/_lib/x402/offer-receipt-issuer.js), key publication [api/x402/did.js](api/x402/did.js) `→ /.well-known/did.json` | Live | What a given wallet **spent** on the platform's paid endpoints. Every settled x402 call issues a signed Offer & Receipt artifact (USE-17) and durably logs it; a buyer connects a Solana or EVM wallet, signs one read-only message (5-minute window, no transaction, no fee) and gets every receipt ever issued to that wallet: endpoint, settled amount, network, explorer-linked tx, the full signed artifact as JSON, plus search and CSV export. The signing message is a fixed four-line string that must stay byte-identical between `buildReceiptsMessage()` (client) and `buildExpectedMessage()` (server); [tests/receipts-lib.test.js](tests/receipts-lib.test.js) pins that contract against a verbatim copy of the server's function. The signed artifact carries no amount and omits the tx hash under the spec §5.2 privacy default, so the row records both separately as our own audit trail (migration [api/_lib/migrations/2026-07-28-x402-receipt-settlement.sql](api/_lib/migrations/2026-07-28-x402-receipt-settlement.sql)); receipts predating that capture report as "N of M priced" rather than under-reporting a total. Issuance requires `OFFER_RECEIPT_JWK` (jws) or `OFFER_RECEIPT_SIGNING_PRIVATE_KEY` (eip712); unset means no receipts are issued at all. Docs: [docs/x402-endpoints.md](docs/x402-endpoints.md) |
diff --git a/docs/ux-flows/10-chat-brain-labs.md b/docs/ux-flows/10-chat-brain-labs.md
index a4f04b6c8..7649ea85c 100644
--- a/docs/ux-flows/10-chat-brain-labs.md
+++ b/docs/ux-flows/10-chat-brain-labs.md
@@ -158,6 +158,7 @@ modules. Routes resolved via `vercel.json` rewrites.
### Club — 3D Pole-Stage Venue (x402) — `/club`
- **Source:** `/workspaces/three.ws/pages/club.html` → scripts: `/x402.js` (wallet/payment modal), `/workspaces/three.ws/src/club-entrance.js` (walk-in alley scene), `/workspaces/three.ws/src/club-gate.js` (cover-charge bouncer), `/workspaces/three.ws/src/club.js` (main pole stage). Supporting modules in `src/`: `club-venue.js`, `club-audio.js`, `club-camera.js`, `club-crowd.js`, `club-queue.js`, `club-bouncer.js`, `club-perf.js`, `club-sequence.js`, `animation-manager.js`.
- **Entry point:** `/club` → `club.html`; entrance scene + door gate + pole stage boot in parallel behind a loading screen.
+- **Entrances:** the same page is served at more than one path, and the path picks the walk-in (`src/club-variant.js`). `/club` opens on the neon alley; `/stripclub` opens on a brick back alley (a CC BY 4.0 Sketchfab model by anthonydpc, credited on screen while it is visible and in `public/club/venue/LICENSES.md`). The cover charge, the pass, the gallery and clubhouse that follow, and the pole stage are shared, so a cover paid at one door is good at the other. An "Entrance" switcher under the agent picker links between them. If an entrance's own alley model cannot be loaded, the walk-in opens on the neon alley instead of failing.
- **Prerequisites / gates:** **x402 wallet payment**: a cover charge settled on-chain via `/api/x402/club-cover`; wallet (Phantom / EVM) connected through `x402.js`. The one door's 402 quotes both USDC and $THREE on Solana (while `X402_ACCEPT_THREE_SOLANA` is on, the default), so the checkout shows a token chooser with each token's real price and either token issues the same pass. Paying in $THREE is optional, not a gate. WebGL required.
- **Steps (7):**
1. Open `/club`; loading screen with real GLB byte-count progress; avatar picker populates (bundled + gallery avatars via `/api/avatars/` and `/api/explore`).
diff --git a/pages/club.html b/pages/club.html
index ab9174771..2b04ed508 100644
--- a/pages/club.html
+++ b/pages/club.html
@@ -950,6 +950,86 @@
.club-agent-browse { padding: 5px 11px; font-size: 11px; }
}
+ /* Entrance switcher: the ways into the club (/club, /stripclub), one
+ link each, sitting under the agent pill and sharing its visibility.
+ Links and data come from src/club-variant.js. */
+ .club-entrance-switch {
+ position: fixed;
+ top: 64px;
+ left: 18px;
+ z-index: 9445;
+ display: flex;
+ align-items: center;
+ gap: 9px;
+ padding: 5px 6px 5px 13px;
+ border-radius: 999px;
+ background: rgba(8, 5, 12, 0.6);
+ border: 1px solid rgba(255, 59, 214, 0.18);
+ backdrop-filter: blur(10px);
+ -webkit-backdrop-filter: blur(10px);
+ box-shadow: 0 10px 34px -14px rgba(0, 0, 0, 0.85);
+ pointer-events: none;
+ opacity: 0;
+ transform: translateY(-10px);
+ visibility: hidden;
+ transition: opacity var(--duration-slow) var(--ease-standard), transform var(--duration-slow) var(--ease-standard), visibility 0s linear var(--duration-slow);
+ }
+ .club-entrance-switch.is-visible {
+ opacity: 1;
+ transform: translateY(0);
+ pointer-events: auto;
+ visibility: visible;
+ transition-delay: 0s;
+ }
+ .club-entrance-list { display: flex; gap: 4px; }
+ .club-entrance-link {
+ padding: 5px 11px;
+ border-radius: 999px;
+ border: 1px solid transparent;
+ color: var(--text-2, #c2a8d8);
+ font: 600 12px/1 'Inter', system-ui, sans-serif;
+ text-decoration: none;
+ white-space: nowrap;
+ transition: border-color var(--duration-base) var(--ease-standard), background var(--duration-base) var(--ease-standard), color var(--duration-base) var(--ease-standard), box-shadow var(--duration-base) var(--ease-standard);
+ }
+ .club-entrance-link:hover { color: #fff; background: rgba(255, 255, 255, 0.07); }
+ .club-entrance-link:active { background: rgba(255, 59, 214, 0.22); }
+ .club-entrance-link:focus-visible { outline: none; border-color: #ff3bd6; box-shadow: 0 0 0 3px rgba(255, 59, 214, 0.25); }
+ .club-entrance-link[aria-current='page'] {
+ color: #ff9ee8;
+ background: rgba(255, 59, 214, 0.12);
+ border-color: rgba(255, 59, 214, 0.35);
+ }
+ @media (max-width: 560px) {
+ .club-entrance-switch { top: 54px; left: 12px; padding: 4px 5px 4px 5px; }
+ .club-entrance-switch .club-agent-label { display: none; }
+ .club-entrance-link { padding: 5px 9px; font-size: 11px; }
+ }
+
+ /* Venue credit: attribution for a third-party environment whose
+ licence requires it (CC BY), shown only while that model is on
+ screen. Filled by setVenueCredit() in src/club-entrance.js. */
+ .club-venue-credit {
+ position: fixed;
+ left: 18px;
+ bottom: 14px;
+ z-index: 9440;
+ max-width: min(46vw, 420px);
+ color: var(--text-3, #7c5d92);
+ font: 500 11px/1.4 'Inter', system-ui, sans-serif;
+ text-shadow: 0 1px 3px rgba(0, 0, 0, 0.9);
+ opacity: 0;
+ visibility: hidden;
+ transition: opacity var(--duration-slow) var(--ease-standard), visibility 0s linear var(--duration-slow);
+ }
+ .club-venue-credit.is-visible { opacity: 1; visibility: visible; transition-delay: 0s; }
+ .club-venue-credit a { color: var(--text-2, #c2a8d8); text-decoration: underline; text-underline-offset: 2px; transition: color var(--duration-base) var(--ease-standard); }
+ .club-venue-credit a:hover { color: #fff; }
+ .club-venue-credit a:focus-visible { outline: 2px solid #ff3bd6; outline-offset: 2px; border-radius: 2px; }
+ @media (max-width: 560px) {
+ .club-venue-credit { left: 12px; right: 12px; bottom: 5px; max-width: none; font-size: 10px; text-align: center; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+ }
+
/* Minimap — top-down radar of the room you're in: your avatar, the
way you're facing, and a pulsing line to the door you're headed
for. Drawn each frame by src/club-entrance.js. */
@@ -2160,6 +2240,11 @@
Browse
</button>
</div>
+ <nav id="club-entrance-switch" class="club-entrance-switch" aria-label="Choose an entrance">
+ <span class="club-agent-label">Entrance</span>
+ <div class="club-entrance-list"></div>
+ </nav>
+ <p id="club-venue-credit" class="club-venue-credit"></p>
<div id="club-minimap" class="club-minimap" aria-hidden="true">
<div class="club-minimap-head">
<span id="club-minimap-label" class="club-minimap-label" data-i18n="club.alley_2">Alley</span>
diff --git a/public/club/venue/LICENSES.md b/public/club/venue/LICENSES.md
index 099f50758..e80ea7cd2 100644
--- a/public/club/venue/LICENSES.md
+++ b/public/club/venue/LICENSES.md
@@ -65,3 +65,27 @@ redistribution beyond three.ws. Regenerate from the source export with:
```sh
npm run build:club-entrance-venue # → space-smugglers-clubhouse.glb
```
+
+## Third-party back alley (the `/stripclub` entrance)
+
+`back-alley.glb` is **not** authored by three.ws. It is the brick back alley the
+`/stripclub` entrance opens on (the first venue of the `stripclub` variant in
+[src/club-variant.js](../../../src/club-variant.js)).
+
+| File | Source | Author | License | Modifications |
+| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- | --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `back-alley.glb` | ["environment ally with bar/strip club"](https://sketchfab.com/3d-models/environment-ally-with-barstrip-club-a98c2e9748b24b7fb781d452814304ef) | [anthonydpc](https://sketchfab.com/tonydpc) | [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) | weld + prune + dedup, textures resized to at most 2048 px and re-encoded as WebP q82, position/normal/UV quantization, Meshopt compression via [scripts/build-club-entrance-venue.mjs](../../../scripts/build-club-entrance-venue.mjs) |
+
+CC BY requires credit wherever the work is shown, so the same title, author,
+source and license are rendered on screen for as long as the model is visible
+(`setVenueCredit` in [src/club-entrance.js](../../../src/club-entrance.js), fed
+by the venue's `credit` block in `src/club-variant.js`). Keep the two in step:
+if this asset is replaced, update the `credit` block and this table together.
+
+Rebuild from the source export: download the GLB from the Sketchfab page above
+(a free Sketchfab login is required), save it in the repo root as
+`environment_ally_with_barstrip_club.glb`, then:
+
+```sh
+npm run build:club-entrance-venue # → back-alley.glb, and prints its bounds + door meshes
+```
diff --git a/scripts/build-club-entrance-venue.mjs b/scripts/build-club-entrance-venue.mjs
index 129e8fe1f..693279479 100644
--- a/scripts/build-club-entrance-venue.mjs
+++ b/scripts/build-club-entrance-venue.mjs
@@ -5,6 +5,10 @@
*
* alleyway.glb → public/club/venue/alleyway.glb
* space_smugglers_club_house_-_dark…glb → public/club/venue/space-smugglers-clubhouse.glb
+ * environment_ally_with_barstrip_club.glb → public/club/venue/back-alley.glb
+ * (the /stripclub entrance, src/club-variant.js; CC BY 4.0, credited in
+ * public/club/venue/LICENSES.md and on screen. Download the GLB from the
+ * Sketchfab page listed there and drop it in the repo root.)
*
* Both raw exports are ~17–21 MB — far too heavy to stream while a visitor
* stands at the door — so we run each through the same GLB → Meshopt + WebP
@@ -25,7 +29,7 @@ import { dirname, resolve } from 'node:path';
import { NodeIO } from '@gltf-transform/core';
import { ALL_EXTENSIONS } from '@gltf-transform/extensions';
-import { weld, prune, dedup, quantize, textureCompress, meshopt } from '@gltf-transform/functions';
+import { weld, prune, dedup, quantize, textureCompress, meshopt, getBounds } from '@gltf-transform/functions';
import { MeshoptEncoder } from 'meshoptimizer';
import sharp from 'sharp';
@@ -42,6 +46,9 @@ const TARGETS = [
{ src: 'space_smugglers_club_house_-_dark_version.glb', out: 'space-smugglers-clubhouse.glb' },
// Gallery corridor you walk through before reaching the club door.
{ src: 'tour.glb', out: 'tour.glb' },
+ // The brick back alley behind /stripclub. Sketchfab names the download after
+ // the model's slug, and a browser may have saved it under the short name.
+ { src: ['environment_ally_with_barstrip_club.glb', 'back-alley-source.glb'], out: 'back-alley.glb' },
];
const mb = (n) => (n / 1024 / 1024).toFixed(2);
@@ -58,9 +65,30 @@ function stripJunkMeshes(doc) {
return removed;
}
+// What the runtime derives from a venue: its bounding height (src/club-variant.js
+// `height` normalises against this) and the door it anchors the cover prompt to
+// (findDoorAnchor in src/club-entrance.js matches /door/i on a mesh node or its
+// parent). Printed per build so a new model is tuned from this output, not by
+// trial and error in the browser.
+function reportVenueShape(doc) {
+ const scene = doc.getRoot().getDefaultScene() || doc.getRoot().listScenes()[0];
+ if (!scene) return;
+ const { min, max } = getBounds(scene);
+ const size = max.map((v, i) => (v - min[i]).toFixed(2));
+ console.log(` bounds (source units): ${size[0]} wide x ${size[1]} tall x ${size[2]} deep`);
+ const doors = doc.getRoot().listNodes().filter((n) => {
+ if (!n.getMesh()) return false;
+ const parent = n.getParentNode();
+ return /door/i.test(n.getName() || '') || /door/i.test(parent?.getName() || '');
+ });
+ if (doors.length) console.log(` door-named meshes: ${doors.map((n) => n.getName() || '(unnamed)').join(', ')}`);
+ else console.log(' door-named meshes: none (the walk-in will exit down the longest axis)');
+}
+
async function compress(io, srcPath, outPath) {
const before = statSync(srcPath).size;
const doc = await io.read(srcPath);
+ reportVenueShape(doc);
const stripped = stripJunkMeshes(doc);
if (stripped) console.log(` stripped ${stripped} junk mesh(es)`);
@@ -95,9 +123,10 @@ async function main() {
mkdirSync(OUT_DIR, { recursive: true });
for (const { src, out } of TARGETS) {
- const srcPath = resolve(ROOT, src);
- if (!existsSync(srcPath)) {
- console.warn(`skip — source not found: ${src}`);
+ const candidates = [].concat(src).map((name) => resolve(ROOT, name));
+ const srcPath = candidates.find((candidate) => existsSync(candidate));
+ if (!srcPath) {
+ console.warn(`skip: source not found: ${[].concat(src).join(' or ')}`);
continue;
}
await compress(io, srcPath, resolve(OUT_DIR, out));
diff --git a/src/club-entrance.js b/src/club-entrance.js
index 9eec752a2..25d02c749 100644
--- a/src/club-entrance.js
+++ b/src/club-entrance.js
@@ -11,6 +11,8 @@
// house interior — until you reach the strip club itself (the pole stage, in
// src/club.js), where you tip dancers to perform.
//
+// Which alley you land in depends on the door you came by: /club and /stripclub
+// serve this same page, and src/club-variant.js maps the path to a venue list.
// The journey is the SEQUENCE list below: every venue is free-walk; you reach
// its exit and the next one fades in. The alley's door takes the cover; the
// last venue hands off to the pole stage. Everything renders into one
@@ -63,10 +65,8 @@ import { getPowerSaver } from './shared/frame-governor.js';
import { log } from './shared/log.js';
import { isExpressEntry } from './shared/club-express.js';
import { loadEnvironment } from './shared/cinematic-render.js';
+import { resolveClubVariant, listClubEntrances } from './club-variant.js';
-const TOUR_URL = '/club/venue/tour.glb';
-const ALLEYWAY_URL = '/club/venue/alleyway.glb';
-const CLUBHOUSE_URL = '/club/venue/space-smugglers-clubhouse.glb';
const AVATAR_URL = '/avatars/default.glb';
const MANIFEST_URL = '/animations/manifest.json';
const PASS_KEY = 'club:pass:v1';
@@ -94,7 +94,6 @@ const MOVE_CLIP_URLS = {
// manifest on first admit (most visitors never pay a cover the same session as
// a reload, so there's no point bundling it with idle/walk up front).
const ADMIT_DANCE_CLIP = 'twerk';
-const VENUE_NAMES = ['Alley', 'Gallery', 'Clubhouse']; // index-aligned with SEQUENCE, for the minimap label
// The agent switcher's catalog: bundled, known-good humanoid rigs that ship with
// the app (so the dropdown always has options offline — Hard rule 9), plus public
@@ -286,11 +285,11 @@ async function start(canvasEl) {
// alley); the rest just lead you to the next place. `door` anchors the exit
// to a modelled doorway (+ seals it) where one exists; interiors exit down
// their longest dimension. The last venue hands off to the strip club stage.
- const SEQUENCE = [
- { url: ALLEYWAY_URL, cover: true, door: true }, // outside — pay the cover here
- { url: TOUR_URL, cover: false, door: false }, // gallery hall
- { url: CLUBHOUSE_URL, cover: false, door: false }, // club interior → the poles
- ];
+ // Which places those are depends on the entrance you came in by: /club and
+ // /stripclub share the stage but not the alley (src/club-variant.js).
+ const variant = resolveClubVariant(window.location.pathname);
+ const SEQUENCE = variant.sequence.slice();
+ setupEntranceSwitch(variant);
// Land in the alley + the avatar first; prefetch the rest so each place is
// ready the moment you walk into it. The loader bar tracks real bytes.
@@ -299,13 +298,29 @@ async function start(canvasEl) {
// The bouncer rides the same batch so he is at his post on the first frame
// instead of popping in beside the door; a failed load just means no bouncer.
const [firstGltf, avatarGltf, bouncerGltf, manifest, idleClipJson, walkClipJson] = await Promise.all([
- loader.loadAsync(SEQUENCE[0].url, (e) => setLoaderProgress('alley', e)),
+ loadFirstVenue(),
loader.loadAsync(AVATAR_URL, (e) => setLoaderProgress('avatar', e)),
loader.loadAsync(BOUNCER_AVATAR_URL).catch((err) => { log.warn('[club-entrance] bouncer load failed', err); return null; }),
fetch(MANIFEST_URL, { cache: 'force-cache' }).then((r) => (r.ok ? r.json() : [])).catch(() => []),
fetch('/animations/clips/idle.json', { cache: 'force-cache' }).then((r) => r.ok ? r.json() : null).catch(() => null),
fetch('/animations/clips/walk.json', { cache: 'force-cache' }).then((r) => r.ok ? r.json() : null).catch(() => null),
]);
+ // An entrance whose own alley can't be fetched opens on its fallback alley
+ // instead: the visitor still walks up to a door and pays the cover, rather
+ // than being dropped straight onto the cover card by the scene-failed path.
+ // SEQUENCE[0] is rewritten to the venue actually mounted so its scale, door
+ // anchoring and credit all describe what is on screen.
+ async function loadFirstVenue() {
+ const first = SEQUENCE[0];
+ try {
+ return await loader.loadAsync(first.url, (e) => setLoaderProgress('alley', e));
+ } catch (err) {
+ if (!first.fallback) throw err;
+ log.warn(`[club-entrance] ${first.url} failed, opening on ${first.fallback.url}`, err);
+ SEQUENCE[0] = first.fallback;
+ return loader.loadAsync(first.fallback.url, (e) => setLoaderProgress('alley', e));
+ }
+ }
const loaded = SEQUENCE.map(() => null); // index-aligned gltf cache
loaded[0] = firstGltf;
for (let i = 1; i < SEQUENCE.length; i++) {
@@ -328,7 +343,8 @@ async function start(canvasEl) {
if (occluder) { scene.remove(occluder); disposeObject(occluder); occluder = null; }
if (env) { disposeObject(env.root); scene.remove(env.root); }
if (!v.cover) bouncer?.unmount();
- env = mountEnvironment(scene, loaded[i].scene);
+ env = mountEnvironment(scene, loaded[i].scene, v.height);
+ setVenueCredit(v.credit);
// Anchor to the modelled door so the prompt + neon frame land on the real
// doorway; interiors skip this and exit down their longest dimension.
doorAnchor = v.door ? findDoorAnchor(env.root) : null;
@@ -506,7 +522,7 @@ async function start(canvasEl) {
camYaw = Math.atan2(path.dir.x, path.dir.z);
updateCamera(1);
setJourneyStep(venueIndex);
- minimap.setVenue(env.box, path.door, VENUE_NAMES[venueIndex] || 'Venue');
+ minimap.setVenue(env.box, path.door, SEQUENCE[venueIndex].name || 'Venue');
}
// ── Input ──────────────────────────────────────────────────────────────
@@ -1193,6 +1209,7 @@ async function start(canvasEl) {
try { disposeGltfLoader(renderer); } catch {}
try { canvasEl.remove(); } catch {}
showHint(false); showJoystick(false); showPrompt(false); showJourney(false); showMinimap(false); showAgentSwitch(false);
+ setVenueCredit(null);
}
}
@@ -1202,7 +1219,55 @@ function showHint(v) { toggle('club-controls-hint', v); }
function showJoystick(v) { toggle('club-joystick', v); }
function showJourney(v) { toggle('club-journey', v); }
function showMinimap(v) { toggle('club-minimap', v); }
-function showAgentSwitch(v) { toggle('club-agent-switch', v); }
+function showAgentSwitch(v) {
+ toggle('club-agent-switch', v);
+ // The entrance switcher is part of the same top-left cluster: it is only
+ // meaningful while you can still walk, so it rides the agent pill's state.
+ toggle('club-entrance-switch', v);
+}
+
+// Entrance switcher: one link per way in, the current one marked. Plain anchors
+// so each entrance is a real navigation (and a middle-clickable, shareable URL).
+function setupEntranceSwitch(variant) {
+ const el = document.getElementById('club-entrance-switch');
+ if (!el) return;
+ const list = el.querySelector('.club-entrance-list');
+ if (!list) return;
+ list.replaceChildren(...listClubEntrances().map((entrance) => {
+ const a = document.createElement('a');
+ a.className = 'club-entrance-link';
+ a.href = entrance.path;
+ a.textContent = entrance.label;
+ if (entrance.key === variant.key) a.setAttribute('aria-current', 'page');
+ return a;
+ }));
+}
+
+// Attribution for a venue whose licence requires it (CC BY): shown for as long
+// as that model is on screen, cleared the moment you walk into the next place.
+function setVenueCredit(credit) {
+ const el = document.getElementById('club-venue-credit');
+ if (!el) return;
+ el.replaceChildren();
+ if (!credit) { el.classList.remove('is-visible'); return; }
+ const link = (href, text) => {
+ const a = document.createElement('a');
+ a.href = href;
+ a.target = '_blank';
+ a.rel = 'noopener noreferrer';
+ a.textContent = text;
+ return a;
+ };
+ el.append(
+ '3D alley: ',
+ link(credit.sourceUrl, `"${credit.title}"`),
+ ' by ',
+ link(credit.authorUrl, credit.author),
+ ', ',
+ link(credit.licenseUrl, credit.license),
+ );
+ el.classList.add('is-visible');
+}
function toggle(id, v) {
const el = document.getElementById(id);
if (el) el.classList.toggle('is-visible', !!v);
@@ -1221,10 +1286,11 @@ function setJourneyStep(i) {
// ── Scene helpers ────────────────────────────────────────────────────────────
-// Normalise an environment to a human-scaled room (height = ROOM_HEIGHT),
-// recentre on the floor at the origin, add it, and return its box + the
-// movement bounds (a margin inside the footprint so you don't clip walls).
-function mountEnvironment(scene, root) {
+// Normalise an environment to human scale (its bounding height becomes `height`,
+// a single-storey ROOM_HEIGHT unless the venue declares its own), recentre on
+// the floor at the origin, add it, and return its box + the movement bounds (a
+// margin inside the footprint so you don't clip walls).
+function mountEnvironment(scene, root, height = ROOM_HEIGHT) {
// Render the walls solid from both faces. These venue GLBs export single-sided
// (FrontSide) walls, so the instant the chase camera grazes or dips behind a
// building face the front faces cull away and you see straight through the
@@ -1242,7 +1308,7 @@ function mountEnvironment(scene, root) {
const box = new Box3().setFromObject(root);
const size = box.getSize(new Vector3());
- root.scale.setScalar(ROOM_HEIGHT / (size.y || 1));
+ root.scale.setScalar(height / (size.y || 1));
const b2 = new Box3().setFromObject(root);
const c = b2.getCenter(new Vector3());
root.position.x -= c.x;
diff --git a/src/club-variant.js b/src/club-variant.js
new file mode 100644
index 000000000..92b305abb
--- /dev/null
+++ b/src/club-variant.js
@@ -0,0 +1,84 @@
+// Which way into the club. The pole stage, the cover charge and the dancers are
+// the same room whichever door you use; a variant only changes the walk-in that
+// src/club-entrance.js plays before the stage opens. The variant is picked from
+// the URL path, so every entrance is a plain shareable link:
+//
+// /club the neon alley (the original walk-in)
+// /stripclub a brick back alley, a third-party CC BY model (credited on screen)
+//
+// Pure data + helpers, no three.js or DOM, so the routing rule is unit-tested
+// without booting a renderer (tests/club-variant.test.js).
+//
+// A venue entry:
+// url runtime GLB under public/club/venue/ (Meshopt + WebP, built by
+// scripts/build-club-entrance-venue.mjs)
+// name minimap label for the room
+// cover true on the venue whose door takes the cover charge
+// door true when the exit anchors to a modelled door mesh; false walks
+// the room's longest dimension instead
+// height metres the model's bounding height is normalised to. Defaults to
+// a single-storey room; an exterior with full building fronts needs
+// its real height or the avatar reads as a giant.
+// fallback venue mounted instead when this one cannot be loaded, so a missing
+// or failed asset never strands the visitor outside the door
+// credit attribution a licence requires us to show while the venue is on screen
+
+const NEON_ALLEY = { name: 'Alley', url: '/club/venue/alleyway.glb', cover: true, door: true };
+const GALLERY = { name: 'Gallery', url: '/club/venue/tour.glb', cover: false, door: false };
+const CLUBHOUSE = { name: 'Clubhouse', url: '/club/venue/space-smugglers-clubhouse.glb', cover: false, door: false };
+
+const BACK_ALLEY = {
+ name: 'Back alley',
+ url: '/club/venue/back-alley.glb',
+ cover: true,
+ door: true,
+ // Four-storey brick frontage with fire escapes, not a single room.
+ height: 13,
+ fallback: NEON_ALLEY,
+ credit: {
+ title: 'environment ally with bar/strip club',
+ author: 'anthonydpc',
+ authorUrl: 'https://sketchfab.com/tonydpc',
+ sourceUrl: 'https://sketchfab.com/3d-models/environment-ally-with-barstrip-club-a98c2e9748b24b7fb781d452814304ef',
+ license: 'CC BY 4.0',
+ licenseUrl: 'https://creativecommons.org/licenses/by/4.0/',
+ },
+};
+
+export const DEFAULT_CLUB_VARIANT = 'club';
+
+export const CLUB_VARIANTS = {
+ club: {
+ key: 'club',
+ path: '/club',
+ label: 'Neon alley',
+ sequence: [NEON_ALLEY, GALLERY, CLUBHOUSE],
+ },
+ stripclub: {
+ key: 'stripclub',
+ path: '/stripclub',
+ label: 'Back alley',
+ sequence: [BACK_ALLEY, GALLERY, CLUBHOUSE],
+ },
+};
+
+/**
+ * Resolve the walk-in variant for a URL path. Trailing slashes and case are
+ * ignored; anything that is not a known entrance gets the default, so an
+ * embed or an odd rewrite still lands in a working club.
+ *
+ * @param {string} [pathname]
+ * @returns {typeof CLUB_VARIANTS[keyof typeof CLUB_VARIANTS]}
+ */
+export function resolveClubVariant(pathname = '') {
+ const clean = String(pathname).toLowerCase().replace(/\/+$/, '');
+ for (const variant of Object.values(CLUB_VARIANTS)) {
+ if (clean === variant.path) return variant;
+ }
+ return CLUB_VARIANTS[DEFAULT_CLUB_VARIANT];
+}
+
+/** Every entrance, in display order, for the HUD's entrance switcher. */
+export function listClubEntrances() {
+ return Object.values(CLUB_VARIANTS).map(({ key, path, label }) => ({ key, path, label }));
+}
diff --git a/tests/club-variant.test.js b/tests/club-variant.test.js
new file mode 100644
index 000000000..49681885c
--- /dev/null
+++ b/tests/club-variant.test.js
@@ -0,0 +1,79 @@
+// Tests for src/club-variant.js: the URL path → walk-in variant rule behind the
+// /club and /stripclub entrances. Pure data, so no renderer or DOM is needed.
+
+import { describe, it, expect } from 'vitest';
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import {
+ CLUB_VARIANTS,
+ DEFAULT_CLUB_VARIANT,
+ resolveClubVariant,
+ listClubEntrances,
+} from '../src/club-variant.js';
+
+const publicDir = resolve(__dirname, '../public');
+
+describe('resolveClubVariant', () => {
+ it('maps each entrance path to its own variant', () => {
+ expect(resolveClubVariant('/club').key).toBe('club');
+ expect(resolveClubVariant('/stripclub').key).toBe('stripclub');
+ });
+
+ it('ignores trailing slashes and case', () => {
+ expect(resolveClubVariant('/stripclub/').key).toBe('stripclub');
+ expect(resolveClubVariant('/StripClub').key).toBe('stripclub');
+ expect(resolveClubVariant('/club/').key).toBe('club');
+ });
+
+ it('falls back to the default entrance for anything else', () => {
+ for (const path of ['', '/', '/club.html', '/stripclub/extra', undefined]) {
+ expect(resolveClubVariant(path).key).toBe(DEFAULT_CLUB_VARIANT);
+ }
+ });
+});
+
+describe('CLUB_VARIANTS', () => {
+ it('gives every entrance exactly one cover door, on the first venue', () => {
+ for (const variant of Object.values(CLUB_VARIANTS)) {
+ const covers = variant.sequence.filter((v) => v.cover);
+ expect(covers).toHaveLength(1);
+ expect(variant.sequence[0].cover).toBe(true);
+ }
+ });
+
+ it('keeps the journey the same length as the four-step HUD expects', () => {
+ for (const variant of Object.values(CLUB_VARIANTS)) {
+ expect(variant.sequence).toHaveLength(3);
+ }
+ });
+
+ it('names every venue for the minimap', () => {
+ for (const variant of Object.values(CLUB_VARIANTS)) {
+ for (const venue of variant.sequence) expect(venue.name).toBeTruthy();
+ }
+ });
+
+ it('backs a third-party alley with a fallback that ships in the repo', () => {
+ const first = CLUB_VARIANTS.stripclub.sequence[0];
+ expect(first.fallback).toBeTruthy();
+ expect(first.fallback.cover).toBe(true);
+ expect(existsSync(resolve(publicDir, `.${first.fallback.url}`))).toBe(true);
+ });
+
+ it('carries a complete credit for the CC BY alley', () => {
+ const { credit } = CLUB_VARIANTS.stripclub.sequence[0];
+ for (const field of ['title', 'author', 'authorUrl', 'sourceUrl', 'license', 'licenseUrl']) {
+ expect(credit[field], field).toBeTruthy();
+ }
+ expect(credit.license).toBe('CC BY 4.0');
+ });
+});
+
+describe('listClubEntrances', () => {
+ it('lists every entrance with a unique path and a label', () => {
+ const entrances = listClubEntrances();
+ expect(entrances.map((e) => e.key).sort()).toEqual(Object.keys(CLUB_VARIANTS).sort());
+ expect(new Set(entrances.map((e) => e.path)).size).toBe(entrances.length);
+ for (const e of entrances) expect(e.label).toBeTruthy();
+ });
+});
diff --git a/vercel.json b/vercel.json
index c72b3080a..c002f66ca 100644
--- a/vercel.json
+++ b/vercel.json
@@ -1822,6 +1822,10 @@
"src": "/club/?",
"dest": "/club.html"
},
+ {
+ "src": "/stripclub/?",
+ "dest": "/club.html"
+ },
{
"src": "/theater/?",
"dest": "/theater.html"
diff --git a/vite.config.js b/vite.config.js
index 9bd9f722a..2adcaafa3 100644
--- a/vite.config.js
+++ b/vite.config.js
@@ -1854,6 +1854,8 @@ const appConfig = {
'/pose-mini/': resolve(root, 'pages/pose-mini.html'),
'/club': resolve(root, 'pages/club.html'),
'/club/': resolve(root, 'pages/club.html'),
+ '/stripclub': resolve(root, 'pages/club.html'),
+ '/stripclub/': resolve(root, 'pages/club.html'),
'/theater': resolve(root, 'pages/theater.html'),
'/theater/': resolve(root, 'pages/theater.html'),
'/stage': resolve(root, 'pages/stage.html'),