How ujjwalvivek/journey works
1. Repository shape
- This is a Rust workspace centered on a 2D action game tech demo.
- The workspace is split into reusable engine code, game/content code, audio-generation crates, release tooling, and a web distribution layer.
2. Core architectural boundary: engine/ vs game/
- engine is the reusable runtime/library layer and appears to be the main public API surface.
- game is the content/application layer that implements the actual gameplay, scenes, player/enemy logic, level handling, and startup flow.
- The README explicitly emphasizes a clean API from engine to game to avoid tight coupling.
3. Engine subsystem
- engine/src is organized around the low-level runtime concerns of a 2D game engine: context, runtime, time, input, camera, physics, sprite/texture handling, animation, UI, audio, math, and atmosphere.
- The engine uses wgpu for rendering, winit for window/input events, egui for UI, gilrs for gamepad input, glam for math, and pollster for async startup.
- Shader assets live under engine/assets/shaders, so rendering is shader-driven and asset-backed rather than hard-coded.
4. Simulation and rendering flow
- The architecture is described as data-oriented, trait-driven, and fixed-step.
- A typical frame flows from platform events into input state, through fixed-step simulation/physics/time, and then into rendering via the engine’s context/runtime layers.
- The presence of physics.rs, time.rs, and runtime.rs suggests the engine owns the deterministic update loop, while camera.rs, sprite.rs, and texture_manager.rs feed the render pass.
5. Gameplay subsystem
- game/src contains the actual metroidvania gameplay: player, enemy, projectile, scene, level, level_editor, start_sequence, benchmark, and config.
- There is a dedicated combat subsystem under game/src/combat with its own FSM, input buffering, and move definitions, which implies combat is treated as a separate gameplay domain.
- game/src/main.rs is the executable entry point; game/src/lib.rs likely binds the game into the engine’s app trait.
6. Input and controls
- Input is split between engine-level event capture and game-level action mapping.
- game/src/input.rs and game/src/combat/input_buffer.rs indicate a layered control model: raw input comes from the engine, then game-specific actions and buffered combat timing are interpreted in gameplay code.
- This is consistent with the README’s focus on jump buffering, coyote time, and precise parry timing.
7. Audio stack
- Audio is intentionally decomposed into two crates: resonance and cadence.
- resonance is the lower-level DSP/sound primitive layer, with modules like oscillator, envelope, buffer, LUT, and patch.
- cadence is the higher-level sequencer/scene/track layer, likely used to generate or schedule music and procedural audio behavior.
- The game asset tree also includes many .ogg effects and ambient/legacy audio, so runtime audio appears to combine authored samples with procedural synthesis/sequencing.
8. Web distribution and browser integration
- web/ is a Vite + TypeScript frontend used to run or package the WASM build in the browser.
- The browser side includes TypeScript components for cadence and resonance, plus shared-audio.ts and a resonance_worklet.js file in public, which strongly suggests Web Audio integration through an audio worklet.
- This layer acts as the browser host/glue, not the gameplay engine itself.
9. Assets and content pipeline
- game/assets contains level data, player assets, effects, and audio files, so the gameplay crate owns most runtime content.
- engine/assets contains shader sources, while web/public contains browser delivery artifacts like the audio worklet and redirects.
- The architecture separates code-owned engine assets from game-owned content assets.
10. Tooling and release infrastructure
- GitHub Actions workflows cover CI, deploy, and publishing, indicating the repo is built and released as both a Rust crate and an npm package.
- tools/release is a substantial Go-based release pipeline with orchestration, semver, stats, and TUI support, so versioning/publishing is treated as its own subsystem.
- tools/versioning appears to support release/version management separately from the main build.
11. Documentation and developer experience
- docs/ is a full mdBook-style documentation site with intro, API, technical docs, and audio docs.
- The repository also includes Zed editor configuration, a Makefile, and release notes, implying the project is optimized for active iteration across Rust and TypeScript.
12. What an architecture diagram should emphasize
- Show game depending on engine, with engine depending on platform/render/audio libraries.
- Show cadence and resonance as a separate audio-generation stack that feeds runtime audio.
- Show web as the browser host around the WASM build, and tools/ plus GitHub Actions as the build/release pipeline around the product.
Main entry points: scene.rs Scene · runtime.rs Runtime · src/lib.rs Engine API · src/lib.rs Game API
Components 21
Engine
Reusable runtime and low-level engine systems
- Engine API · Public engine surface that the game builds on
engine/src/lib.rs - Runtime · Owns startup and fixed-step execution flow
engine/src/runtime.rs - Context · Rendering and frame context boundary
engine/src/context.rs - Input · Platform and controller input capture
engine/src/input.rs - Time · Frame timing and deterministic update cadence
engine/src/time.rs - Physics · Core world and movement simulation
engine/src/physics.rs
Game
Gameplay, scenes, combat, and content glue
- Game Main · Executable entry point
game/src/main.rs - Game API · Binds gameplay into the engine app model
game/src/lib.rs - Scene · Top-level gameplay scene orchestration
game/src/scene.rs - Player · Player movement and interactions
game/src/player.rs - Combat · Buffered FSM-based combat system
game/src/combat/mod.rs - Level · Level loading and progression logic
game/src/level.rs - Game Audio · Gameplay-specific sound triggering and integration
game/src/audio.rs
Audio
Procedural audio generation stack
- Cadence · Higher-level sequencing and scene-driven audio logic
cadence/src/lib.rs - Resonance · Low-level synthesis and sound primitives
resonance/src/lib.rs - Audio Tool · CLI orchestration for audio generation and web export
tools/audio/src/main.rs
Web
Browser host and WASM distribution layer
Tooling
Release and auxiliary build tools
- Release Tool · Go-based orchestration for versioning and publishing
tools/release/main.go - Versioning · Standalone version management utility
tools/versioning/main.go
Docs
Developer and technical documentation
- Docs · mdBook documentation set for engine, audio, and technical notes
docs/src/SUMMARY.md
Connections 24
- Game Main → Game API: starts · Executable boots the game layer
- Game API → Engine API: uses · Gameplay is built on the reusable engine API
- Game API → Scene: drives · Game entry binds scene orchestration
- Scene → Player: updates · Scene owns player state and flow
- Scene → Level: loads · Scene advances through levels and content
- Scene → Combat: runs · Scene coordinates combat interactions
- Scene → Game Audio: triggers · Scene and gameplay events emit audio cues
- Combat → Player: buffers · Combat logic depends on player timing and input
- Runtime → Context: renders · Runtime hands off to the frame/render context
- Runtime → Input: polls · Runtime ingests platform input each frame
- Runtime → Time: steps · Fixed-step timing governs simulation cadence
- Runtime → Physics: simulates · Runtime advances physics and movement systems
- Engine API → Runtime: exports · Library surface exposes the core loop
- Engine API → Input: exports · Library surface exposes input handling
- Cadence → Resonance: builds on · Sequencing layer sits on top of DSP primitives
- Audio Tool → Cadence: generates · Audio tooling orchestrates cadence-based content
- Audio Tool → Resonance: renders · Tooling can render or transform resonance assets
- Web Host → Audio UI: hosts · Browser entry mounts shared audio components
- Audio UI → Cadence: adapts · Web layer bridges cadence concepts into the browser
- Audio UI → Resonance: adapts · Web layer bridges resonance synthesis into Web Audio
- Release Tool → Versioning: coordinates · Release pipeline uses version management support
- Docs → Engine API: documents · Documentation covers the engine API and architecture
- Docs → Cadence: documents · Documentation covers the audio generation stack
- Docs → Game API: documents · Documentation covers gameplay and runtime flow