How romapervushin1234/pachoink-newton works
1. This repo is a browser-based simulation/game called Pachoink-Newton. The architecture is split between a JavaScript frontend that owns the app loop, rendering, UI, and input, and a Rust/WASM module under wasm/ that likely provides the Newtonian gravity-heavy computation path.
2. The browser entry point is index.html, which boots the JavaScript app from src/main.js. That file is the top-level coordinator for the client runtime and is the main place where the subsystems are wired together.
3. The core runtime is organized as a set of focused modules in src/:
- state.js for shared game/application state
- input.js for user interaction
- camera.js for viewport/world transforms
- generation.js for creating levels/objects/content
- particles.js for simulation entities and motion
- scoring.js for point calculation and progress tracking
- renderer.js for drawing
- ui.js for interface overlays and controls
- config.js for tunable constants
- Newtonian_pachoink.js as the domain-specific glue or exported simulation entry point
4. The likely data flow is: input changes state, the main loop advances generation/particles/scoring, and the renderer consumes the updated state to draw the frame. The camera sits between simulation state and rendering, translating world coordinates into view coordinates.
5. The state boundary is important: it appears to be the shared source of truth for the current scene, user progress, and simulation parameters. Other modules should be viewed as consumers or mutators of that central state rather than owning their own isolated copies.
6. The simulation boundary is split by responsibility, not by feature. particles.js and generation.js likely handle the evolving world model, while scoring.js interprets outcomes. This separation suggests the app keeps physics/behavior logic distinct from presentation logic.
7. The rendering boundary is cleanly isolated in renderer.js and ui.js. That implies two visual layers: the world canvas/scene rendering and a separate UI layer for buttons, indicators, and score display. camera.js influences only the world layer, not the UI layer.
8. The wasm/ directory is a second major subsystem. It is a Rust crate (Cargo.toml, Cargo.lock, src/lib.rs) compiled to WebAssembly, likely used to accelerate gravity/physics calculations or other numerically heavy work that benefits from Rust performance and deterministic behavior.
9. The JS/WASM integration boundary is probably centered in src/Newtonian_pachoink.js. That file likely abstracts the WASM exports behind a JavaScript-friendly interface so the rest of the app can treat the simulation engine as a module rather than dealing with raw WASM details directly.
10. server.js is the lightweight host/runtime for development or local serving. It is not the application logic; it exists to deliver the static browser assets and make the client/WASM bundle runnable from a Node-based environment.
11. In architectural terms, this repo is mostly a single-page interactive simulation with:
- a presentation layer in the browser
- a domain/simulation layer in JavaScript
- a compute accelerator in Rust/WASM
- a thin server wrapper for hosting
12. For a diagram, the main arrows should be:
- user input → input.js → state.js
- state/update loop → generation.js / particles.js / scoring.js
- simulation data → renderer.js / ui.js
- camera transforms → renderer.js
- JS simulation glue → Newtonian_pachoink.js ↔ wasm/lib.rs
- server.js → serves index.html + client/WASM assets
Main entry points: main.js Main Loop · state.js State · renderer.js Renderer · config.js Config
Components 14
Host
Local server and delivery of the browser app
- Server · Static host for the browser app
server.js - Entry Page · Browser entry point that loads the client app
index.html
Browser Client
JavaScript runtime for input, simulation, rendering, and UI
- Main Loop · Top-level client coordinator and wiring point
src/main.js - State · Central source of truth for scene and progress
src/state.js - Input · User interaction and event handling
src/input.js - Camera · Viewport and world coordinate transforms
src/camera.js - Generation · Creates levels, objects, or simulation content
src/generation.js - Particles · Evolving world entities and motion
src/particles.js - Scoring · Points, outcomes, and progression tracking
src/scoring.js - Renderer · Renders the world scene
src/renderer.js - UI · On-screen controls and status overlays
src/ui.js - Config · Shared tunable parameters
src/config.js - Newton Bridge · JavaScript-facing wrapper around the simulation engine
src/Newtonian_pachoink.js
WASM Compute
Rust module compiled to WebAssembly for heavy simulation work
- WASM Core · Rust WebAssembly module for heavy compute
wasm/src/lib.rs
Connections 21
- Server → Entry Page: serves · Hosts the browser entry page and client assets
- Entry Page → Main Loop: boots · Loads the JavaScript application entry point
- Main Loop → Input: wires · Connects input handling into the app loop
- Main Loop → State: owns · Coordinates the shared application state
- Main Loop → Generation: drives · Advances content or level generation
- Main Loop → Particles: updates · Runs the simulation entities and motion
- Main Loop → Scoring: evaluates · Computes points and progress from outcomes
- Main Loop → Renderer: ticks · Triggers frame rendering from updated state
- Main Loop → UI: updates · Refreshes overlays and controls
- Main Loop → Newton Bridge: uses · Calls into the simulation bridge for compute-heavy work
- Input → State: mutates · Converts user actions into state changes
- Generation → State: writes · Adds or changes world content in shared state
- Particles → State: reads/writes · Consumes and updates simulation state
- Scoring → State: reads · Derives score and progression from state
- Renderer → State: reads · Draws the current simulation state
- Renderer → Camera: applies · Uses camera transforms for world rendering
- UI → State: reads · Displays state-driven HUD and controls
- Newton Bridge → WASM Core: bridges · Wraps the Rust/WASM exports behind a JS interface
- Config → Generation: configures · Supplies tunable generation parameters
- Config → Particles: configures · Supplies simulation constants
- Config → Renderer: configures · Supplies rendering-related constants