Getting started

This page takes you from a fresh clone to the game running in the dev server, the website, and the native apps.

Prerequisites

• Bun for dependency installation and root scripts
• Node.js >=22.12 for the build toolchains; use npm scripts to run Astro
• Java 21, Android SDK Platform 37.2, and current Android command-line tools (minimum supported device API remains 21)
• Xcode, Ruby >=3.2, and Bundler (for iOS)

See Dependencies and upgrades for exact versions and compatibility holds.

Quick start

git clone https://github.com/jonathanperis/speedy-bird-lynx.git
cd speedy-bird-lynx
bun install --frozen-lockfile
bun run dev

This starts the Rspeedy dev server with hot module replacement. The game is accessible at:

• Web preview: http://localhost:3000/__web_preview?casename=main.web.bundle
• Lynx bundle: http://localhost:3000/main.lynx.bundle

To view on a mobile device, open the Lynx bundle URL in Lynx Explorer or Lynx Go (replace localhost with your machine’s IP).

Building for production

bun run build

This outputs:

• dist/main.lynx.bundle — native bundle for Android/iOS
• dist/main.web.bundle — web bundle

Android

bun run build
cd android && ./gradlew assembleDebug

The APK is at android/app/build/outputs/apk/debug/app-debug.apk. Gradle stages the current root bundle and sound effects into generated assets; no manual copy is needed. Install via adb install or transfer to your device. Run ./gradlew lintDebug for Android API checks, or ./gradlew assembleRelease for a release APK.

For release builds with signing, see CI/CD pipeline.

iOS

bun run build
cd ios
bundle install
bundle exec pod install
open SpeedyBird.xcworkspace

Pick a simulator or device and run. The project packages the current dist/main.lynx.bundle and the sounds directly; no copy step is needed. Running on a device requires selecting your own signing team in Xcode; CI always builds unsigned. See Native host apps for the UI tests and project generator.

Web / GitHub Pages

The public web surface is the Astro site in docs/. It renders the landing page, plays the real ReactLynx build on it, and generates wiki pages from docs/wiki/*.md. Astro 7 requires Node.js >=22.12, so use the npm scripts for the docs dev server/build even though dependencies are installed from bun.lock.

The home page loads main.web.bundle and the Lynx web runtime from docs/public/play/, so build them at the repository root first (and again after changing the app):

bun run build:site
cd docs
bun install --frozen-lockfile
npm run dev

For a production build:

npm run build
npm run check:site
npm run preview

The static output is written to docs/out/. Development, preview, and production serve the host root and /docs/ (set SITE_BASE to change the base). The Deploy Web workflow runs bun run build:site and then deploys that production output. Content authoring and asset maintenance are documented in docs/README.md.

Web surfaces

In development the host needs two terminals. Pass ?bundle=<url> to load a bundle from elsewhere. For a self-contained build, run bun run build and then bun run build:web-host: dist-web-host/ then contains the host, main.web.bundle, the audio, and the bridge module, and bunx rsbuild preview --config rsbuild.web-host.config.ts serves it. The dev and preview servers send cross-origin isolation headers, but the Lynx web runtime does not need them: any static server works, including GitHub Pages under a project path.

Project commands