How wowsims/wotlk works
Project type and purpose
• This is a full-stack simulation framework for World of Warcraft WotLK Classic.
• Backend: Go-based simulation engine (CLI, WASM, & server binary).
• Frontend: TypeScript/React UI with templated pages for each class/spec.
• Data exchange: Google Protocol Buffers define the API between sim and UI.
File structure
• Top level:
• cmd/… → standalone CLI (wowsimcli).
• sim/… → simulation code in Go, with sim/wasm entrypoint for WebAssembly, sim/core for engine logic, sim/register_all.go to register specs.
• ui/… → UI code: ui/core is shared React/TS templates and proto utils; ui/<spec> folders contain spec-specific pages and JSON presets; ui/worker houses web workers for off-thread sim.
• proto/… → .proto definitions for messages & enums.
• assets/… → static DB files loaded by the sim.
• Dockerfile, makefile, GitHub workflows for CI/CD.
README for additional insights
• Architecture is based on a single sim engine shared by all specs.
• UI is generated from templates; sim code compiles to WASM for in-browser runs or is invoked by Go HTTP server.
• Build & deployment use Makefile and Docker; GitHub Actions auto-deploy master to GitHub Pages.
a. Main components:
• Browser UI: React/TS app + Web Workers.
• WASM Sim Engine: Go code compiled to WebAssembly, loaded in sim_worker.js.
• Go Server Binary (wowsimwotlk): hosts static assets and can run simulations server-side.
• CLI (wowsimcli): for batch simulations & decoding links.
• Proto Definitions: single source of truth for messages (in proto/).
• Assets & Database: static JSON/BIN in assets/database.
• External scrapers/tools: Python/Go scripts in tools/ to generate DB inputs.
b. Relationships & flows:
1. Developer runs make host → UI build (via Vite or embedded in Go) → served at /wotlk/<spec>.
2. Browser(UI) → sends simulation request (via Proto-serialized message) to sim worker.
3. sim_worker loads WASM sim engine → invokes Simulation.RunOnce, reads assets (in-memory DB) → returns results.
4. net_worker can proxy requests to Go server in dev mode (for server-side sim).
5. CLI uses the same proto & sim core to run headless sims or decode links.
c. Architectural patterns & design principles:
• Single codebase for engine logic, reused in CLI, WASM, and server.
• Template-driven UI generation: common ui/core + spec-specific JSON.
• Web Workers to offload CPU-heavy sim from main thread.
• Proto-driven API to enforce type safety across Go and TS.
• Makefile and Docker for reproducible builds & CI.
d. Key technologies & libraries:
• Go >=1.21, google.golang.org/protobuf, Wasm.
• TypeScript, React, Vite (via vite.config.js), Web Workers.
• Docker, Make, GitHub Actions (deploy & tests).