@flumen-publish/games

CLI and SDK for hosting browser games, interactive web experiences, interactive 3D models and 3D visualizations on Flumen. Use it to share Three.js/React Three Fiber/Babylon.js games and scenes, Phaser, PixiJS and PlayCanvas games, Unity WebGL/Godot Web exports, other HTML5 games, WebGL apps, product configurators, architectural walkthroughs and immersive web experiences by browser link. These use the same games commands and gameId. Supply a browser client with index.html and all model/texture assets, or supported source that builds one. A raw GLB/GLTF or native 3D file needs a viewer; this CLI does not convert native formats or run offline rendering. Version 3 uploads a private draft, builds and validates it, then opens its playable preview. Use --open-editor to open the editor instead. Agents can pass title, description, category, tags, engine, cover and intended visibility directly with the upload. The author reviews these fields and any optional video preview, tests the game, then either clicks Publish game or explicitly asks the agent to publish that reviewed revision. Updating an existing game also creates a draft: its live build, text and public link remain available until publication.

npx @flumen-publish/games@3 --version
npx @flumen-publish/games@3 login
npx @flumen-publish/games@3 games inspect .
npx @flumen-publish/games@3 games check GAME_ID
npx @flumen-publish/games@3 games upload . --title "My source project"
npx @flumen-publish/games@3 games upload --dir ./dist --title "My little game"
npx @flumen-publish/games@3 games upload --source . --title "A garden" --description "Walk through my garden." --category nature --tags "garden,relaxing" --thumbnail ./cover.png --visibility unlisted
npx @flumen-publish/games@3 games upload --game GAME_ID --dir ./dist --title "My game" --no-open
npx @flumen-publish/games@3 games draft GAME_ID
npx @flumen-publish/games@3 games update GAME_ID --version 2 --description "What I made and wanted to share."
npx @flumen-publish/games@3 games update GAME_ID --version 3 --video ./walkthrough.mp4
npx @flumen-publish/games@3 games update GAME_ID --version 4 --thumbnail ./cover.png
# Only after the author approves the latest reviewed revision:
npx @flumen-publish/games@3 games publish GAME_ID --version 5

A non-empty --title (up to 100 characters) is required for every upload, including updates. Folder and archive names are never used as fallback titles. Publication requires a ready build, a title and visibility (public or unlisted). Description, cover and video preview are optional. The description may be empty and is limited to 5,000 characters. The editor combines details and visibility on one review page, following the completed upload step. Agents must ask the author to confirm the title and whether to include a description, and wait for an explicit answer before uploading or changing either field.

ZIP uploads include an explicit Content-Length for object-storage compatibility. A single outer project folder, as found in GitHub ZIP downloads, is detected automatically; ambiguous multi-project roots are rejected. Draft/update help works without signing in. Account checks preserve the actual error, including network and keyring access problems.

Imported projects may contain .htaccess. It is accepted in directory/source uploads and ZIPs, but Flumen does not apply Apache rules: the worker omits this file from browser artifacts and reports a warning to review any required redirects or headers. Sensitive files such as .htpasswd and .env remain forbidden. Game pages support HTTPS analytics, scripts, styles, fonts and import maps without requiring those dependencies to be bundled or removed. HTTP dependencies may still be blocked by the browser as mixed content.

For a prebuilt ZIP that also contains package.json, use games upload --archive game.zip --kind static --title "My game" to skip source compilation. Use --kind source to request a source build explicitly. Without this flag, ZIPs keep their existing automatic detection. Directory uploads keep --dir for ready files and --source for compilation. With games upload [folder], the CLI detects a finished export or source project; omitted folder means the current directory. games inspect [folder] shows the same decision and package-manager/build plan without login or upload. Source builds support npm, pnpm, Bun and Yarn; explicit flumen.json settings override inference.

When the API advertises a direct-upload completion path, the CLI confirms the exact upload generation immediately after the object-storage PUT. Builds start without waiting for the background upload scan. Older APIs continue to work through polling. Default Vite source builds use a relative asset base so their output works under a versioned preview URL; an explicit project build command is preserved.

The upload result includes { gameId, editorUrl, previewUrl, previewExpiresAt, progress, readiness, status: "draft" }. The signed preview expires after approximately 30–60 minutes; games status GAME_ID returns a fresh link. ready means files are built and validated. readiness.automatedLaunchCheck is not_run; verify actual gameplay in a browser. --no-open and global --json suppress browser opening. If opening fails, the URLs are still printed. A draft's default audience after publication is Anyone with the link: visible on the author's profile and accessible by link, excluded from Feed, Explore and search. Omitting --visibility on an update preserves its intended audience; an explicit value sets the draft audience. Metadata passed with upload appears in Details without a separate games update command. It reaches the live game only after a separate publication command or editor action. games publish GAME_ID --version REVIEWED_VERSION publishes a prepared draft. Agents must show the final fields and audience, ask for explicit publication approval, and wait for the answer. Approval to upload or edit metadata is not publication approval. The version is required: a changed revision returns a conflict and requires renewed review and approval. games update accepts --visibility public|unlisted to set the agreed audience before review.

Video is optional for both uploads and publication. If supplied: MP4 with H.264 or WebM (VP8/VP9/AV1), up to 60 seconds and 100 MB; the server checks the actual file. A failed video replacement keeps the previous video. PNG/JPEG/WebP covers are optional; the editor can use a video frame as the cover. games draft returns the current version; updates use that version to reject conflicts instead of overwriting newer work.

Version 3.1.1 renames the SDK world calls to game calls without aliases; update imports before upgrading.

SDK exports uploadGame, getGameDraft, updateGame and publishGameDraft(gameId, reviewedVersion). There are no legacy SDK aliases; upload and publication use separate explicit names. In CLI 3, games publish publishes an existing reviewed draft; use games upload for files. Publication returns { gameId, publicUrl }. This is a breaking change from version 2. Old uploads cannot bypass the draft workflow on the updated server; upgrade to version 3 for editor URLs, versioned edits and separate publication. Keep gameId for subsequent uploads so the game link, reactions and comments remain together.

Delete a game

Version 3.1.2 adds flumen-publish games delete GAME_ID. It permanently deletes the whole owned game, including its published version, draft, comments and uploaded files. The interactive command asks you to type the exact game ID. For automation, use flumen-publish --json games delete GAME_ID --yes only after the owner explicitly approves that target. SDK: deleteGame(gameId, { confirm: true }); missing confirmation is rejected before authentication or network access. Requires games:publish. The response is { gameId, deleted: true }; server shutdown and file cleanup continue in the background. If the response is lost, check the owned game list before retrying the same ID.

Diagnostics

games status GAME_ID returns current phase, phase timings, build plan and warnings. games logs GAME_ID --type build --lines 200 reads the retained build log; --type runtime reads the active game server log. Both require ownership. Empty runtime logs do not prove successful gameplay. Global --json keeps machine-readable output; progress messages use stderr.

Environment

| Variable | Purpose | |----------|---------| | FLUMEN_API_URL | Platform API origin (default https://games.flumen.tech) | | FLUMEN_GAMES_UPLOAD_RESOURCE_URL | OAuth resource (default ${FLUMEN_API_URL}/api/games-upload) | | FLUMEN_CLI_CLIENT_ID | First-party OAuth client id (flumen-cli) | | FLUMEN_TOKEN / --token | Bearer token for CI, overrides saved login | | FLUMEN_TOKEN_STORAGE | auto, file, or keyring | | FLUMEN_CLI_ALLOW_DCR=1 | Dev only: dynamic client registration |

Credentials live in ~/.config/flumen/auth.json or the OS keyring (com.flumen.flumen-publish). Neither credentials nor bearer tokens are placed in editor URLs or copied instructions.

Release

Deploy API, worker and web with migration 0012_world_drafts.sql before distributing version 3. Version 3.1 also requires API/worker migration 0013_publish_progress.sql for phase metrics. The platform API image now includes ffprobe (ffmpeg package). Publishing the npm package is a separate release step:

pnpm --filter @flumen-publish/games publish --access public

Multiplayer servers

Publish the browser client and a Node.js 24 HTTP/WebSocket server together with --source. Add flumen.json at the project root; each directory contains its own package.json:

{
  "version": 1,
  "client": { "rootDirectory": "client", "outputDirectory": "dist" },
  "server": { "rootDirectory": "server", "startCommand": "npm start", "healthPath": "/health" }
}

flumen-publish games upload --source ./my-game --title "Together"

The server listens on 0.0.0.0:$PORT and returns HTTP 200 at its health path. The browser obtains its server URL from await window.Flumen.ready; call window.Flumen.reconnect() after a disconnect. Set database credentials and other secrets in Studio, rather than uploading .env files. Hosting must be enabled on the target Flumen instance. An example is available in the Flumen repository under templates/multiplayer.

Upload limits

ZIP up to 1 GiB, 15,000 files, and 2 GiB unpacked by default. The CLI streams ZIP bytes directly to storage and sends size and SHA-256 separately. Oversized archives fail before upload. The server validates each archive before replacing a working game.

games check <id> checks a ready private preview using fresh authorization and automatic cookie/redirect handling. It checks HTML and up to 12 directly referenced same-origin resources; repeat --path /assets/main.js to select paths. JSON includes per-resource HTTP results and browserGameplay: "not_run"; no scripts are executed and no private URLs/cookies are printed. A failed check exits nonzero. The API must include the preview-check endpoint.

Automatic project inspection uses the same package metadata rules for folders and ZIPs. Known framework presets infer build commands and output directories; explicit flumen.json settings win. Next.js/SvelteKit projects need static export configuration for browser hosting. A ready HTML export is not rebuilt merely because it includes package.json.