Skip to content

README.md

Latest commit

 

History

History
66 lines (56 loc) · 5.45 KB

README.md

File metadata and controls

66 lines (56 loc) · 5.45 KB

Stellar HTML5 Demo (Beamable + Stellar) 🎮

This repository showcases how to integrate the Stellar SDK within the Beamable ecosystem for an HTML5 game built on Next.js. It covers Beam bootstrap, custodial and external wallet attachment, content/inventory sync, commerce, and the Tower Destroyer gameplay loop.

What to Expect In-Game

  • 🎯 Arcade slingshot loop: fire balls to topple towers, earn score, and clear stages.
  • 🗺️ Progression: advance through campaign stages, repeat loops for higher difficulty, and unlock mechanics as you go.
  • 🧰 Loadouts: collect different ball types (normal, multishot, fire, laser) with varying speed/power; a default ball is granted automatically.
  • 💰 Economy: earn coins from wins, sync them to Beam/Stellar, and purchase ball listings from the in-game shop.
  • ⏳ Minting delay: Stellar mints settle on a fixed cadence; after purchases/grants/coin sync it can take ~10–15 seconds before inventory reflects the change. The UI keeps the loading/refresh state up during this window; if something looks “stuck”, wait a moment and then tap Refresh in the shop.
  • 🛡️ Identity flow: set an alias, auto-attach a custodial wallet, and optionally attach an external Stellar wallet via WalletConnect-style popups.

Quick Start

  • 🚀 npm install
  • 🗂️ Add .beamable/connection-configuration.json with your CID/PID (see below).
  • 🧪 Create .env.local as needed and run npm run dev.

Configuration

Primary source of truth: .beamable/connection-configuration.json (consumed via app/api/beam-config/route.ts):

{ "cid": "your-cid", "pid": "your-pid", "host": "https://api.your-cluster.com" }

Environment overrides:

  • NEXT_PUBLIC_BEAM_ENV / BEAM_ENV: environment key (prod, stg, dev, or custom).
  • NEXT_PUBLIC_BEAM_HOST / BEAM_HOST: override API host without editing .beamable.
  • NEXT_PUBLIC_BEAM_CID / NEXT_PUBLIC_BEAM_PID: fallback if the file is missing.
  • NEXT_PUBLIC_STORE_CONTENT_ID: store content id for commerce (default stores.Store_Nf).
  • NEXT_PUBLIC_DEBUG_LOGS=true: enable verbose client logging.

Example .env.local:

NEXT_PUBLIC_BEAM_ENV=stg
NEXT_PUBLIC_BEAM_HOST=https://api.stg.beamable.com
NEXT_PUBLIC_STORE_CONTENT_ID=stores.Store_Nf
NEXT_PUBLIC_DEBUG_LOGS=true

NPM Scripts

  • 🛠️ npm run dev: Start Next.js in development.
  • 📦 npm run build: Production build.
  • 🚦 npm run start: Serve the built app.
  • 🔍 npm run lint: Lint via scripts/run-lint.cjs.
  • ✅ npm run test: Vitest suites (physics, content caching, commerce caching).

Architecture Overview

  • ✨ Beam bootstrap (lib/beam.ts): Resolves config from .beamable, env vars, or window.__BEAM__; registers custom environments when a host override is present; initializes Beam with clientServices and the generated StellarFederationClient; auto-logs guests to ensure tokens.
  • ⭐ Stellar federation (lib/beam/player.ts, beamable/clients/StellarFederationClient.ts): Custodial identity attach, external identity attach/login, WalletConnect URL builder, and microservice endpoints (addItem, purchaseBall, updateCurrency, plus the external wallet callback endpoints externalAddress / externalSignature).
  • 🔔 Notifications (lib/notifications.ts): Raw websocket subscriptions for external-auth-address and external-auth-signature, with payload normalization for the wallet handshake.
  • 📦 Content / Inventory / Commerce (lib/beamContent.ts, lib/beamInventory.ts, lib/commerceManager.ts): Content fetch and caching, inventory helpers over the generated OpenAPI calls, store + listing resolution with cache keys by store/manifest.
  • 🏗️ Game loop and UX (components/Game/*, hooks/*): Canvas physics and state, campaign progression, ball loadouts, currency sync, shop purchases, identity bootstrap, wallet pop-up orchestration, and overlays for player info and campaign flow.

Microservice Core (StellarFederation)

  • Location: BeamableServices/services/StellarFederation.
  • Identity namespaces: custodial StellarWeb3Identity, external StellarWeb3ExternalIdentity (StellarFederationCommon/StellarFederationCommon.cs).
  • Startup (Program.cs): preload common assembly, prepare microservice, register shutdown hook, and start the hosted background worker.
  • DI: ServiceRegistration.AddFeatures auto-registers IService types; Endpoints/ServiceRegistration wires auth/inventory endpoints.
  • Initialization (StellarFederation.InitializeServices): set up Mongo extensions, validate realm config, create realm wallet, initialize Soroban contracts, and start the scheduler (non-DEBUG builds).
  • Client-callables: StellarConfiguration, CreateAccount, GetAccount, inventory helpers (UpdateCurrency, AddItem, RemoveItem, UpdateItems), plus admin Jobs/BlockProcessor.
  • External callbacks: ExternalAddress and ExternalSignature feed wallet-connect bridge responses and trigger player notifications.
  • Microservice readme

Workflow Tips

  • 📌 Keep .beamable/connection-configuration.json aligned with your target cluster; prefer env overrides for quick host/env switches.
  • 🪟 If a popup blocker prevents wallet attach, use the logged URL or enable popups and retry.
  • ✅ After SDK updates, re-run npm run test and sanity-check wallet attach and commerce flows end-to-end.