isle.pizza Frontend

A custom web frontend for the Emscripten port of isle-portable, allowing LEGO Island to run directly in modern web browsers.

Requirements

• Node.js 20 or later

Quick Start

1. Clone the repository:

   git clone https://github.com/isledecomp/isle.pizza.git
   cd isle.pizza
   

2. Install dependencies:

   npm install
   

3. Obtain the game files (isle.js and isle.wasm) by building the Emscripten version of isle-portable, then copy them to the project root.

4. Set up the LEGO Island game assets:

   npm run prepare:assets
   

   This will prompt you for the path to your LEGO Island installation or mounted ISO and create the necessary symlinks. You can also provide the path directly:

   npm run prepare:assets -- -p /path/to/your/LEGO
   

5. Generate the save editor asset bundle (requires game assets from step 4):

   npm run generate:save-editor-assets
   

   This extracts animations, sounds, textures, and character icons from the game files into save-editor.bin, used by the save editor's 3D previews.

6. Start the development server:

   npm run dev
   

7. Open the URL shown in the terminal (usually http://localhost:5173).

Architecture

The project consists of three components:

Component	Directory	Required	Description
Frontend	Root	Yes	Svelte SPA served from Cloudflare R2
API Worker	server/	No	Hono-based Cloudflare Worker handling auth, cloud sync, crash reports, and memories (backed by D1)
Multiplayer Relay	External	No	WebSocket relay for peer-to-peer multiplayer (source)
Share Worker	worker/	No	Cloudflare Worker that injects Open Graph meta tags for /memory/* and /scene/* share URLs

The frontend degrades gracefully without the optional components — single-player gameplay, the save editor, and the full UI all work without them.

Backend Setup (Optional)

API Worker

Optional. Enables authentication, cloud sync, crash reports, and memory features.

docker build -t isle-pizza-api -f server/Dockerfile . && docker run --rm -p 8788:8788 isle-pizza-api

The server starts on port 8788. To enable Discord authentication, create server/.dev.vars with:

BETTER_AUTH_SECRET=<random secret>
DISCORD_CLIENT_ID=<your Discord app client ID>
DISCORD_CLIENT_SECRET=<your Discord app client secret>

Multiplayer Relay

Optional. Enables the multiplayer lobby and in-game networking. The relay server lives in the isle-portable repository.

From the isle-portable repo:

docker build -t isle-relay -f docker/relay/Dockerfile . && docker run --rm -p 8787:8787 isle-relay

Environment Variables

Build-time (frontend)

Variable	Default	Description
RELAY_URL	ws://localhost:8787	Multiplayer relay WebSocket URL
API_URL	http://localhost:8788	Backend API URL
BUILD_VERSION	null	Version string injected into the build

These are configured in site.config.js and injected via Vite's define.

Runtime (API worker)

Variable	Description
BETTER_AUTH_SECRET	Encryption key for auth sessions
DISCORD_CLIENT_ID	Discord OAuth2 application ID
DISCORD_CLIENT_SECRET	Discord OAuth2 secret

Set these in server/.dev.vars for local development.

Scripts

Command	Description
npm run dev	Start development server with hot reload
npm run build	Build for production (copies game files to dist/, injects service worker)
npm run build:ci	CI build (skips copying game files)
npm run check	Run svelte-check with warnings as errors
npm run preview	Preview the production build locally
npm run prepare:assets	Set up LEGO Island game assets via symlinks
npm run generate:save-editor-assets	Extract save editor assets into save-editor.bin
npm run deploy	Deploy to dev environment (R2)
npm run deploy:assets	Deploy to dev environment including game assets
npm run deploy:prod	Deploy to production environment (R2)
npm run deploy:prod:assets	Deploy to production including game assets

Project Structure

isle.pizza/
├── src/
│   ├── App.svelte         # Main application component
│   ├── app.css            # Global styles
│   ├── stores.js          # Svelte stores for state management
│   ├── core/
│   │   ├── formats/       # Binary file parsers/serializers (WDB, save games, animations, textures)
│   │   ├── rendering/     # OGL renderers (BaseRenderer, VehiclePartRenderer, ActorRenderer, etc.)
│   │   ├── savegame/      # Save game constants, actor data, color tables
│   │   └── ...            # Audio, OPFS, cloud sync, auth, service worker, asset loading
│   └── lib/               # UI components and pages (save editor, multiplayer, scene player, etc.)
├── server/                # API worker (Cloudflare Workers + D1)
│   ├── src/               # Hono routes: auth, memories, cloud sync, crash reports
│   ├── migrations/        # D1 database migrations
│   ├── Dockerfile         # Local development container
│   └── wrangler.toml      # Cloudflare Workers config
├── worker/                # Share/OG worker (Cloudflare Workers + R2)
│   ├── src/               # Open Graph tag injection for share URLs
│   └── wrangler.toml      # Cloudflare Workers config
├── scripts/               # Build, asset generation, and deploy scripts
├── src-sw/                # Service worker source (Workbox-based caching and offline support)
├── public/
│   └── images/            # UI images (menu buttons, tab icons)
├── site.config.js         # Build-time environment config (RELAY_URL, API_URL)
├── index.html             # HTML entry point
├── isle.js                # Emscripten JS (not in repo, build from isle-portable)
├── isle.wasm              # Emscripten WASM (not in repo, build from isle-portable)
├── save-editor.bin        # Packed save editor assets (not in repo, generated)
└── LEGO/                  # Game data directory (not in repo, symlinked)

Building the Game Files

The isle.js and isle.wasm files are not included in this repository. To obtain them:

1. Follow the isle-portable build instructions for the Emscripten target
2. Copy the resulting isle.js and isle.wasm to this project's root directory

Alternatively, a Docker image that bundles the runtime with this frontend is available.

CI

The build workflow runs on pushes to master and on pull requests. It installs dependencies, runs npm run check (svelte-check), and builds with npm run build:ci. Deployment is done manually via the deploy scripts.

Tech Stack

• Svelte 5 - UI framework
• OGL - 3D rendering for save editor previews
• Vite - Build tool and dev server
• Workbox - Service worker and offline support
• Hono - Backend API framework (Cloudflare Workers)
• better-auth - Authentication (Discord)
• Cloudflare D1 - Database for the API worker
• Cloudflare R2 - Static asset hosting and share worker storage

License

See LICENSE for details.