How lewdry/zorkweb works
1. Overall shape
- This is a mostly client-side SvelteKit application that serves classic Zork games in the browser.
- The core architecture is: SvelteKit routing/UI shell on top of a browser-based Z-machine interpreter, with all game ROMs shipped as static assets.
2. Primary runtime boundary
- There is no visible backend domain logic in the repository tree.
- The important execution boundary is browser vs. static hosting: the app ships HTML/CSS/JS plus the Zork ROM files, and the game runs entirely in the user’s browser.
3. Routing structure
- src/routes/+layout.svelte and src/routes/+layout.js define the global app layout and shared behavior across pages.
- src/routes/+page.svelte is the entry/home page.
- src/routes/[game]/+page.js and src/routes/[game]/+page.svelte implement a dynamic route for selecting and playing a specific game, likely mapping URLs like /zork1, /zork2, /zork3.
4. Game selection and page-level data flow
- The [game] route is the key navigation boundary: it receives the game identifier from the URL, resolves which ROM to load, and renders the player UI for that game.
- This is the point where app navigation becomes game runtime setup.
5. Game execution subsystem
- src/lib/jszm.js is the likely interpreter/runtime layer for the Z-machine.
- It is the core engine that consumes a Zork ROM and produces the interactive text adventure behavior in the browser.
- This subsystem is distinct from the UI: it handles game state, command processing, and output generation.
6. Player UI subsystem
- src/lib/components/ZPlayer.svelte is the central interactive component.
- It likely bridges user input, interpreter output, and auxiliary modes such as voice interaction.
- This component is the main integration point between the Svelte app and the interpreter runtime.
7. Shared navigation and app chrome
- src/lib/components/Navbar.svelte provides persistent navigation across the app.
- It is part of the app shell rather than the game engine, and likely lets users move between games or pages.
8. Static game assets
- The ROMs live in static/roms/zork1.z3, zork2.z3, and zork3.z3.
- Because they are in static, they are served directly by the host and fetched by the browser at runtime.
- This is the main content/data source for the interpreter; there is no evidence of ROM fetching from an API.
9. Supporting assets and presentation
- src/app.css, Tailwind config, and DaisyUI styling shape the visual presentation.
- Styling is an app-wide concern, but it does not affect the game logic architecture except by defining the shell around the player.
10. Voice mode capability
- The README calls out speech-to-text and text-to-speech support.
- That functionality is likely encapsulated in the player layer rather than a separate backend service, meaning the browser uses local Web APIs for voice input/output while still relying on the same interpreter pipeline.
11. Build and framework boundary
- The app is built with SvelteKit and bundled via Vite.
- svelte.config.js, vite.config.js, and tailwind.config.js define the framework and asset pipeline, but they do not introduce additional runtime subsystems.
12. Deployment model
- .github/workflows/deploy.yml indicates automated deployment via GitHub Actions.
- Given the static ROMs and browser-only runtime, the deployment is likely a static site deployment rather than a server application.
13. Important diagram boundaries
- A useful architecture diagram should show:
- User browser
- SvelteKit app shell / routes
- ZPlayer UI
- JSZM interpreter
- Static ROM assets
- Optional browser speech APIs for voice mode
- The key data flow is: route selection → ROM fetch from /static/roms → interpreter execution in browser → text/UI updates back to the player.
14. What is not present
- No database, auth service, API layer, or server-side game engine is evident in the repository structure.
- That absence is architecturally important: the application is designed as a self-contained, front-end-hosted interactive fiction player.
Main entry points: +page.js Game loader · ZPlayer.svelte ZPlayer · +layout.svelte App shell · roms Zork ROMs
Components 18
Browser runtime
Client-side execution boundary in the user’s browser.
- Player · Person interacting with the text adventure in the browser.
- Browser host · Executes the app and interprets game logic entirely client-side.
- Speech APIs · Browser speech-to-text and text-to-speech capabilities used for voice mode.
SvelteKit app
Routing, shell, and interactive game UI.
- Layout data · Shared route-level setup and page behavior.
src/routes/+layout.js - App shell · Global SvelteKit shell around the pages.
src/routes/+layout.svelte - Home page · Entry page for the application.
src/routes/+page.svelte - Game loader · Resolves the selected game from the URL and prepares page data.
src/routes/[game]/+page.js - Game page · Dynamic route that renders the selected game.
src/routes/[game]/+page.svelte - Navbar · Persistent navigation shared across the app.
src/lib/components/Navbar.svelte - ZPlayer · Main game UI that connects input, output, and voice features.
src/lib/components/ZPlayer.svelte - JSZM · Browser-based Z-machine runtime that executes Zork ROMs.
src/lib/jszm.js - Lib entry · Shared library export surface.
src/lib/index.js - App styles · Global presentation and layout styling.
src/app.css
Static content
ROM assets and host-served files used at runtime.
Other components
- Deploy workflow · GitHub Actions deployment for the static app.
.github/workflows/deploy.yml
Connections 22
- Player → Browser host: plays · The player uses the app in the browser.
- Browser host → App shell: loads app · The browser loads the SvelteKit shell.
- App shell → Layout data: shared behavior · The shell uses route-level shared setup.
- App shell → Navbar: renders · Persistent navigation is part of the app chrome.
- App shell → Home page: hosts · The shell wraps the entry page.
- Home page → Game loader: navigates to · Users choose a game route from the entry page.
- Game loader → Game page: provides data · The dynamic route prepares the selected game page.
- Game page → ZPlayer: mounts · The game page renders the interactive player.
- ZPlayer → JSZM: drives · The UI sends commands and receives game output from the interpreter.
- ZPlayer → Speech APIs: uses voice · Voice mode is implemented through browser speech capabilities.
- JSZM → Zork ROMs: loads ROMs · The interpreter consumes static game files.
- Zork ROMs → Zork I: contains · Static asset for Zork I.
- Zork ROMs → Zork II: contains · Static asset for Zork II.
- Zork ROMs → Zork III: contains · Static asset for Zork III.
- ZPlayer → App styles: styled by · The player and shell are presented through global styles.
- Browser host → Deploy workflow: deployed by · The static client is built and deployed via GitHub Actions.
- Browser host → JSZM: executes · Interpreter logic runs entirely client-side.
- Game loader → Zork I: selects · The route resolves the requested game asset.
- Game loader → Zork II: selects · The route resolves the requested game asset.
- Game loader → Zork III: selects · The route resolves the requested game asset.
- Lib entry → ZPlayer: re-exports · Shared library surface exposes the main component.
- Lib entry → JSZM: re-exports · Shared library surface exposes the interpreter module.