How jimzical/jyrocity works
1. What this repo is
- A small real-time browser game built around a Node.js server, Three.js rendering in the browser, and WebSockets for live phone-to-game control.
- It is not a traditional multi-page app with backend data storage; the main architecture is a three-party interaction: desktop browser, phone browser, and server relay.
2. Primary runtime boundary
- server.js is the central backend process.
- It likely serves the HTML pages, static JS/assets, and maintains the WebSocket channel that connects the phone controller to the game client.
- There’s no sign of a database or external API dependency; state is probably kept in memory and is session-based.
3. Client roles
- views/index.html: landing page / entry point for the desktop or host.
- views/game.html: the actual game display, where the 3D scene runs.
- views/phone.html: mobile controller UI, used after scanning the QR code.
- These are distinct browser surfaces with different responsibilities rather than a single SPA.
4. Game rendering subsystem
- public/game.js is the main 3D/game logic.
- It uses Three.js to render the flight scene described in the README as a Wii Resort “Island Flyover” style experience.
- The game client consumes live control input and maps it to camera motion / flight behavior.
5. Phone controller subsystem
- public/phone.js handles the mobile-side input capture.
- The README states it uses the phone’s gyroscope as the control source, so this file likely reads orientation/motion events and sends them over the network.
- The phone acts like an external controller rather than rendering the game itself.
6. QR / pairing flow
- public/qr.js likely generates or displays the QR code that encodes the phone URL.
- This is the pairing boundary between the host page and the controller page.
- The QR code is the user-facing mechanism to join the phone to the current session.
7. Real-time data flow
- The control path is: phone gyroscope input → phone browser JS → WebSocket → server → game browser JS → camera movement.
- This is the core architectural loop and the main reason WebSockets matter here: it needs low-latency, bidirectional updates.
- The server likely acts as a relay/broker rather than an authoritative game engine.
8. Static assets and 3D content
- The public/models/imaginary_city_i folder contains glTF assets (scene.gltf, scene.bin, textures, license), indicating the city environment is loaded as a 3D model asset package.
- public/skybox and public/floor provide environment geometry/sky visuals.
- These assets are loaded by the browser game client, not processed server-side.
9. Deployment / exposure layer
- The project expects ngrok for public access, which matters because phones on another device/network need to reach the local server.
- The batch scripts under scripts/ and runner.bat automate starting the server and ngrok, suggesting a Windows-oriented developer workflow.
- So the operational topology is local Node server tunneled to the internet for mobile access.
10. System boundaries to diagram
- Separate the architecture into:
- Node server: HTTP/static hosting + WebSocket coordination
- Desktop game browser: Three.js scene and flight camera
- Phone browser: gyroscope input UI
- Static asset layer: HTML, JS, models, textures, skybox
- Tunnel/exposure layer: ngrok
- The important dependency is not a database or backend service, but the real-time message path between controller and game.
11. State and synchronization
- The application appears to synchronize only interactive control state, not persistent gameplay state.
- Any pairing/session state is likely transient and managed in memory by the server.
- That makes the architecture lightweight, with the server primarily coordinating connections rather than storing content.
12. How to think about it in one sentence
- This repository is a browser-based 3D flight demo where a phone acts as a live gyro controller, connected through a Node/WebSocket relay and deployed via ngrok for cross-device access.
Main entry points: server.js Server · game.js Game logic · runner.bat Runner · ngrokRunner.bat Ngrok run
Components 17
Backend
Node server and real-time session coordination
- Server · HTTP hosting and WebSocket coordination for paired devices
server.js
Browser surfaces
Desktop host, game view, and phone controller pages
- Home page · Entry surface for the desktop host session
views/index.html - Game page · Desktop browser surface that renders the 3D flight scene
views/game.html - Phone page · Mobile browser surface used to join and steer the session
views/phone.html
Client logic
Browser-side game, controller, and QR modules
- Game logic · Main 3D scene, camera motion, and live control application
public/game.js - Phone input · Captures motion input from the phone and sends control updates
public/phone.js - QR pairing · Generates or displays the code used to connect the phone to the host
public/qr.js
Assets
3D environment and static scene resources
- City model · Imaginary city environment package loaded by the game client
public/models/imaginary_city_i/scene.gltf - Model data · Mesh and geometry payload for the city environment
public/models/imaginary_city_i/scene.bin - Textures · Image assets for the city model surfaces
public/models/imaginary_city_i/textures - Skybox · Background sky visuals for the flight scene
public/skybox - Floor · Ground or horizon geometry for the scene
public/floor
Operations
Local run scripts and tunnel exposure
- Runner · Convenience entry point for starting the local app and tunnel flow
runner.bat - Server run · Starts the Node server during local development
scripts/serverRunner.bat - Website run · Starts the browser-facing website workflow
scripts/websiteRunner.bat - Ngrok run · Starts the public tunnel used for phone access
scripts/ngrokRunner.bat - Ngrok URL · Helper for retrieving or managing the public tunnel address
scripts/ngrokUrl.bat
Connections 20
- Server → Home page: serves · Hosts the landing page for the desktop session
- Server → Game page: serves · Hosts the game display page
- Server → Phone page: serves · Hosts the mobile controller page
- Server → Game logic: streams · Relays control state to the game client over WebSockets
- Server → Phone input: streams · Receives controller updates from the phone client
- Home page → QR pairing: uses · The host page exposes pairing via QR code
- Game page → Game logic: loads · Bootstraps the browser game runtime
- Phone page → Phone input: loads · Bootstraps the mobile controller runtime
- Game logic → City model: loads · Imports the 3D scene model
- Game logic → Model data: loads · Uses mesh and geometry data for rendering
- Game logic → Textures: loads · Uses texture assets for the model
- Game logic → Skybox: uses · Renders the background environment
- Game logic → Floor: uses · Renders ground or horizon geometry
- Phone input → Server: sends input · Pushes gyroscope-derived control data to the relay
- QR pairing → Phone page: points to · Encodes the controller join surface
- Runner → Server run: invokes · Coordinates the development startup flow
- Runner → Ngrok run: invokes · Brings up the public tunnel for external devices
- Runner → Website run: invokes · Starts the browser-facing site workflow
- Ngrok run → Ngrok URL: uses · Resolves the tunnel address for sharing
- Ngrok run → Server: exposes · Publishes the local server to remote phones