Hypercho Games

Hypercho Games is a Next.js App Router, React, TypeScript, and Tailwind marketplace for AI-native browser games. It includes server-rendered route metadata, discovery, media-rich game pages, an embedded player, a local creator-preview flow, and a hardened TypeScript publisher CLI/MCP/reference receiver.

The complete project is open source under the MIT License. See CONTRIBUTING.md before proposing a change and SECURITY.md for responsible disclosure.

Environment configuration

Copy .env.example to .env.local. Browser-visible NEXT_PUBLIC_* values are bundled into the frontend; secrets must never use that prefix.

Variable	Purpose
NEXT_PUBLIC_HYPERCHO_GAMES_ORIGIN	Trusted storefront origin, such as https://game.hypercho.com.
NEXT_PUBLIC_MARKETPLACE_CATALOG_URL	Exact public catalog endpoint.
NEXT_PUBLIC_MARKETPLACE_API_URL	Receiver origin used when an exact catalog URL is not set.
NEXT_PUBLIC_PUBLISH_ENDPOINT	Endpoint placed into the copyable MCP configuration.
NEXT_PUBLIC_SOURCE_REPOSITORY_URL	Public source repository linked from /open-source.
NEXT_PUBLIC_PUBLISHER_LOGIN_URL	Human-safe sign-in URL agents open before a confirmed upload.
HYPERCHO_GAMES_ORIGIN	Canonical storefront origin used in publish receipts.
HYPERCHO_PLAY_ORIGIN	Isolated receiver and game-asset origin.
USERMANAGER_MARKETPLACE_ENDPOINT	UserManager marketplace control-plane base URL.
MARKETPLACE_SERVICE_TOKEN	Private receiver-to-UserManager credential.

Run the marketplace

Requirements: Node.js 20.11 or newer and npm.

npm install
npm --prefix tools/publisher install
npm run publisher:build
npm run receiver

In a second terminal:

npm run dev

Open the URL printed by Next.js, normally http://localhost:3000. The app uses http://127.0.0.1:8787/api/games during local development and the configured storefront origin in production unless NEXT_PUBLIC_MARKETPLACE_API_URL is set. To read UserManager's public catalog directly, set the exact endpoint with NEXT_PUBLIC_MARKETPLACE_CATALOG_URL, for example https://api.hypercho.com/Marketplace/games.

Hypercho UserManager backend

hypercho_usermanager owns marketplace MongoDB metadata. The upload receiver calls its protected marketplace API instead of holding production database credentials:

export USERMANAGER_MARKETPLACE_ENDPOINT='http://127.0.0.1:9979/Marketplace'
export MARKETPLACE_SERVICE_TOKEN='replace-with-a-random-service-secret'
npm run receiver:usermanager

UserManager stores ownership and releases in the shared Hypercho database collections marketplace_games and marketplace_releases. The receiver reports "storage":"usermanager" from /health and fails closed when the API is unavailable. Browser builds remain in the hardened asset store; they are never inserted into MongoDB.

Publish the included example

With the receiver running:

node tools/publisher/dist/cli.js validate \
  --manifest examples/publisher/game-manifest.json \
  --bundle examples/publisher/game

node tools/publisher/dist/cli.js publish \
  --manifest examples/publisher/game-manifest.json \
  --bundle examples/publisher/game

Refresh Discover to see the release and launch it in the sandboxed player. Publisher v0.1 intentionally accepts free releases only; paid commerce requires checkout, entitlements, and payouts that are not faked here.

Connect an agent

Start with the rendered agent guide at /agent or its machine-readable Markdown twin at /agent.md. It teaches the supported upload flow, immutable version-based edits, and the guarded stop required for deletion requests while no removal tool exists. Use the absolute path to tools/publisher/dist/mcp.js in your MCP client. It exposes validate_game_bundle and publish_game; publishing defaults to dry-run and requires explicit confirmation. The agent can upload the browser build, banner, screenshots, trailer, description, categories, AI disclosure, and release metadata in one validated package. The complete configuration, manifest contract, multi-publisher credentials, reverse-proxy/public-origin setup, and security model are in docs/publishing.md.

Verify

npm run verify

Visual QA evidence, including matched Steam reference captures, is under artifacts/qa/.

Deployment boundary

The repository ships a production-shaped reference receiver, not an already-provisioned hosted service. Deploy the Next.js storefront at https://game.hypercho.com, with discovery at /discover, listings at /game/<slug>, and publishing at /publish. Set the receiver's --marketplace-origin https://game.hypercho.com so every non-draft receipt uses that canonical listing URL. Host untrusted browser builds on a separate registrable user-content domain such as https://play.hypercho.games; a public deployment still needs TLS, durable asset storage, publisher credentials, backups, and a configured catalog URL.