tinyworld-integrations

name	tinyworld-integrations
description	Use when changing Tiny World Builder API, webhook, SSE, MCP, plugin, or automation examples.

Tiny World Integrations

The app has browser-local integration points plus a small Netlify account backend:

• Account/profile/cloud-save functions live under netlify/functions/. profile.mjs, builds.mjs, share.mjs, and assets.mjs are routed to /api/profile, /api/builds, /api/share, and /api/assets via each function's exported config.path.
• Auth helpers should resolve the trusted site/Identity base from the same deploy-origin chain used elsewhere, including TINYWORLD_SITE_URL, before Netlify deploy URL fallbacks. Do not derive Identity verification targets from request-controlled origins.
• PartyKit durable flush buffers must clear every successfully-posted pending bucket in the res.ok branch (resources, tax payouts, GOLD events, etc.) so retries do not duplicate already-granted durable rewards.
• Worlds MMO grid size: the saved world payload (data.gridSize) is authoritative. Treat worlds.grid_size as cached metadata that can be stale; DTOs, previews, pricing/count derivation, and room entry should prefer/sync the payload size so an 8x8 map is not shown as 20x20 in multiplayer.
• Wallet/social functions also live under netlify/functions/: wallet.mjs verifies Phantom-signed Solana wallet challenges and reads $TINYWORLD balances/activity from RPC, wallet-payments.mjs creates Solana Pay payment intents, players.mjs tracks online presence/search/chat requests/parties, and livekit-token.mjs issues LiveKit room tokens when LIVEKIT_URL, LIVEKIT_API_KEY, and LIVEKIT_API_SECRET are configured.
• Community functions: community.mjs (/api/community) backs the /community Discord-lite page — rooms, DMs, members, bans, blocks, invites; tables auto-create + seed on first request. Channel names are forced lowercase and the super-owner (TINYWORLD_COMMUNITY_OWNER, default jasonkneen) is made an owner of every room each request via ensureCommunityDefaults. Only staff (super-owner / TINYWORLD_COMMUNITY_STAFF) or a room owner can create/delete channels and ban; the same admin flag gates every privileged action. Members must pass an anti-AI human check (community_verifications) AND have a mandatory Twitter/X handle on their profile (GitHub optional) before they can post/DM/join — saveSocials writes the bare handles to profiles.twitter/profiles.github (idempotent ALTER TABLE ... ADD COLUMN in ensureTables; migration 20260615020000_add_profile_socials.sql). Bootstrap returns me.profileComplete; the page shows a forced "Complete your profile" modal until Twitter is set and renders both handles on profile cards. Members can fully edit their profile (display name, bio, avatar, handles) via saveProfile (alias saveSocials). Avatars are an allowlisted preset set under assets/avatars/*.png (keys in AVATAR_KEYS) — no user image uploads, so no NSFW image risk. All user-authored text (display name + bio) is run through checkTextSafety, a two-layer filter (hard substrings + whole-word, leet/spacing-normalized) that rejects sexual / nudity / abusive / hateful content. Tested in tests/community-profile.test.mjs. community.html signs users in in-page (no bounce to the builder): it loads vendor/tinyworld-auth.js via the import map for Netlify Identity email login/signup and calls /api/wallet for Phantom login, storing the session under the shared tinyworld:auth:wallet-session.v1 key.
• Community moderation webhook: community-webhook.mjs (/api/community/webhook) is a server-to-server endpoint for an agent (Hermes) to ban/unban/block/hide or restore/delete messages/purge spam/delete rooms. Auth is a shared secret (TINYWORLD_COMMUNITY_WEBHOOK_SECRET) via x-tinyworld-signature: sha256=<hmac of raw body> (preferred) or x-webhook-secret. Shared primitives live in lib/community-moderation.mjs; community.mjs also emits outbound message.created events to HERMES_COMMUNITY_WEBHOOK_URL (signed, fire-and- forget) so the agent can observe and react. Full reference: docs/community-webhook.md.
• User auth is Netlify Identity. The browser bridge is self-hosted through vendor/tinyworld-auth.js with an import map to vendored @netlify/identity / gotrue-js; do not reintroduce a remote identity widget script.
• The builder should not show working-looking account UI on hosts that cannot serve Netlify Identity. Treat 404/405 /.netlify/identity/* failures from the browser getSettings() probe or login calls as "auth unavailable": hide sign-in/account commands, keep local/static building usable, and leave cloud save/share/collab actions gated off. For local account work, use Netlify dev at http://localhost:8888/tiny-world-builder.
• Profile image fields stored through /api/profile, /api/admin-users, or community preset-avatar saves must be absolute http(s) URLs. Preset avatar paths under assets/avatars/*.png are normalized with the trusted site origin from TINYWORLD_SITE_URL / Netlify URL / deploy URL envs before validation and persistence; already-absolute URLs are left unchanged.
• Account API fetches must send Authorization: Bearer <nf_jwt> when possible and credentials: 'same-origin' so Netlify Functions can resolve the current Identity user. Wallet login uses the same bearer path with signed tw-wallet-v1... session tokens stored under tinyworld:auth:*.
• For local account/function work, run npx netlify dev and use http://localhost:8888/tiny-world-builder; that port keeps the auth/account UI enabled while the plain static dev server remains anonymous.
• Cloud worlds are stored as full TinyWorld JSON in Netlify Database builds rows. Existing rows update through PUT /api/builds?id=<id> so named localStorage worlds can stay bound to one cloud row instead of creating duplicates. Public share links create immutable-ish rows in world_shares and load through same-origin ?share=<id> / /api/share?id=<id>.
• Multiplayer/shared building uses PartyKit separately from Netlify Functions. partykit.json points at party/index.js, local development runs with npm run party:dev on port 1999, and browser rooms connect only when a URL includes ?party=, ?room=, or ?collab=. Collaborate links should reuse a /api/share id as both the world snapshot id and the PartyKit room id: /tiny-world-builder?share=<id>&party=<id>.
• Shared build/collab rooms are public-observer by default: second and later PartyKit connections are admitted as viewer seats, not held in a lobby. Host clients heartbeat public room metadata to /api/collabs; the home page feed and /collabs page list those rooms with observer links (observe=1). This public visibility must not grant edit authority; edits still require a host-assigned role plus server-side island/zone checks.
• Closing a shared build is a two-layer operation: host clients send room.close to PartyKit so every connected peer receives room.closed and no replacement host is promoted, and they POST { action: 'close', roomId } to /api/collabs so the public registry stores a short-lived tombstone in collab_room_closures. Heartbeats for tombstoned rooms must return { closed: true } instead of recreating the listing.
• Admin collab moderation lives on /collabs: authenticated world-admin sessions call /api/collabs with { action: 'hide', roomId } to add a short-lived collab_room_hides tombstone that removes a room from public lists without disconnecting occupants, or { action: 'adminClose', roomId } to use the close tombstone. When a host sees that close tombstone on its registry heartbeat, the client must send PartyKit room.close before closing its socket so connected peers get the same shutdown event as a manual host stop.
• Shared build owners are tracked from the /api/share row. /api/collabs copies world_shares.owner_auth_id/profile_id into collab_rooms, exposes GET /api/collabs?mine=1 for the builder world-menu "Shared rooms" section, and lets the owner/admin hide (make private), unhide, or ownerClose. GET /api/collabs?roomId=<id>&control=1 can return a signed tinyworld-collab-control token; the builder sends control.claim to PartyKit so the original sharer/admin can reclaim host controls when reopening their own room link instead of staying an observer.
• Collaborative build zones are transient PartyKit room permission data, not saved world cells. Host clients send zones.set; the server sanitizes zones, stores editor zoneIds, and must gate every non-host cell.set against assigned active zones. Client outlines/labels and local edit checks are UX and desync prevention only; do not rely on them as the authority.
• MMO economy/multiplayer extraction lives in packages/tinyworld-mmo-core/. It is a dependency-free ESM package for shared GOLD allowance, resource tax, ledger, join-command, and interest-snapshot contracts. Use it when wiring the TinyWorld economy guide into PartyKit or Netlify Functions instead of copying constants between runtime files.
• Tinyverse published-world navigation no longer uses the tinyverse-nexus hub. /api/worlds should hide that slug from lists and direct loads, published world data should normalize to one center stargate with dest: '__world-picker', and PartyKit safeSpawn() should prefer that gate so players arrive where the in-world picker exit is.
• Tinyverse/lobby access is locked to the Jason account allowlist in netlify/functions/lib/tinyverse-access.mjs. Do not use accountMeetsCriteria() or a raw profiles.lobby_access flag as the authoritative gate; migrations should keep lobby_access default false and clear it for every non-allowlisted profile.
• Tinyverse room join/refresh payloads use compact cells. Terrain-only cells may be [x,z,terrain]; object/resource cells are [x,z,terrain,kind]. Keep the renderer validator and applyState() tolerant of both tuple lengths.
• Explicit resource-bearing custom assets use object-form cells with economy: { resource, charges?, label? }. Live resources are currently fish, ore, plants, and meat; normalize through packages/tinyworld-mmo-core/normalizeWorldResourceSpec(...) in PartyKit and Netlify code instead of inferring resources from visual materials or copying constants. Compact tuple cells remain the default for ordinary terrain/kind saves.
• Tinyverse multiplayer rooms are runtime/play/moderation surfaces only. Do not add live island building controls, adminSave, build-role seats, or world.refresh board replacement inside PartyKit rooms. Island editing and version publication must live in the dedicated draft/version flow.
• Local custom assets are account data too: /api/assets stores one asset_libraries row per profile containing custom voxel-build stamps and saved asset templates. Browser hooks in saveCustomVoxelBuildStamps() and saveAssetTemplates() queue a cloud sync after login.
• Local Netlify Database failures are expected in some netlify dev sessions. Translate 503 Netlify Database is not available... responses into a friendly account/cloud status or warn toast, never a red production-style error toast, raw database message, or visible Local DB offline wording.
• Wallet/player social functions rely on netlify/database/migrations/20260602120000_wallet_players_social.sql. If those tables are missing in local Netlify dev, classify Postgres 42P01 with isMissingRelations(...) and return a setup-oriented 503 instead of logging raw missing-relation errors as generic 500s.
• Phantom wallet linking and wallet login must stay challenge/response based: the browser asks Phantom to sign the server-issued message and the function verifies the Ed25519 signature against the Solana public key before linking or minting a wallet session. Do not accept a posted wallet address as proof of ownership. Wallet login requires TINYWORLD_WALLET_SESSION_SECRET (or TINYWORLD_AUTH_SECRET) for HMAC-signed challenge/session tokens. $TINYWORLD mint/payment values come from env (TINYWORLD_TOKEN_MINT, TINYWORLD_PAYMENT_WALLET, optional SOLANA_RPC_URL) rather than client constants.
• Database schema changes belong in netlify/database/migrations/*.sql. Deploy previews get their own database branch, so use a preview deploy for real Identity + DB verification; local netlify dev is useful for functions but is not a complete Identity social-login test.

Browser-local integration points:

• Outbound webhooks live in tiny-world-builder.html under // -------- API / webhooks / SSE bridge --------.
• Optional browser-local probes must be opt-in so the static app stays console-clean: the Cluso in-page embed is LOCAL-DEV-ONLY, injected at runtime by tools/dev-server.js (assets in gitignored cluso/); it must never be referenced by committed/shipped HTML; model-stamp API endpoints load only with ?modelApi=1, ?modelStampApi=1, window.__TWB_MODEL_STAMP_API_ENABLED__ = true, or localStorage['tinyworld:features:model-stamp-api']='1'.
• fireWebhook(event, payload) batches editor mutations and POSTs { source: 'tiny-world-builder', events } to the configured Developer-panel webhook URL.
• Inbound automation uses EventSource against the configured Developer-panel SSE URL. Each SSE data: payload must be one JSON command accepted by applyRemoteCommand.
• Supported inbound ops include place / set_cell, clear, reset, plus runtime-only vehicle controls: vehicle_spawn, vehicle_set_goal, vehicle_controls, vehicle_remove, and vehicle_clear.
• Runtime vehicles must not pass through each other. Keep traffic behavior in the runtime layer: collision radius + yield radius, brake when another vehicle is inside the envelope, and reroute around occupied road cells after a short blockage when an alternate road path exists.
• Placed objects on paths are live traffic blockers. isVehicleDrivableCell should allow path cells only when the main kind/extras do not occupy the tile, while bridge cells remain drivable. Call refreshVehiclesForWorldObstacleChange from world edit paths so active auto vehicles reroute immediately when the user drops or removes an obstacle.

Examples live under plugins/examples/:

• webhook-receiver.js captures outbound webhook batches.
• sse-command-relay.js exposes /sse for the browser and /command for external clients.
• send-command.js is a small CLI for the relay.
• mcp-stdio-bridge.js is a dependency-free MCP stdio server that calls the relay and reads the webhook log.
• vehicle-road-demo.js is a dependency-free MCP client/demo runner that talks to mcp-stdio-bridge.js, paints a visible road/water/bridge network, spawns runtime vehicles, and retargets them in a loop so the browser remains watchably active.
• The app also supports browser-native shareable vehicle demo URLs:
  • ?demo=vehicles&seed=tide-ridge-428 creates the small/default visible road demo.
  • ?demo=vehicles-large&seed=metro-culdesac-20&stats=1 creates the default 20×20 scale test with arterial/ring roads, bridge crossings, cul-de-sac endpoints, and 36 autonomous vehicles on long routes.
  • Large-demo params: size= / mapSize= / grid= / gridSize= accept the nearest valid demo grid size from 12 through 20 (12, 16, 20); cars= / carCount= / vehicles= / vehicleCount= accept 1..120 and are capped by available unique endpoints. Keep these demos visually self-identifying: show an active badge, hide overlays that cover the road network, and make vehicles obvious with beacons/markers. During local demo work, tools/dev-server.js should make bare http://localhost:3000/ and no-query http://localhost:3000/tiny-world-builder redirect to the small seed so the user can simply open the port or remembered app URL and watch it. Use the large URL explicitly for scale/perf checks.

When changing command shape, update the app bridge and these examples together.