How yuu6883/markovjuniorweb works
Project type and purpose
• This is a full-stack TypeScript port of the MarkovJunior procedural content generator.
• It runs in the browser (React/TSX frontend), in Node.js (CLI), and optionally via WebAssembly for performance-critical algorithms.
• It loads XML model definitions and voxel rules, executes a Wave Function Collapse-style interpreter, and renders or exports .vox files.
File structure
• src/
• core engine modules:
– src/interpreter.ts, src/search.ts, src/rule.ts
– src/mj-nodes/* → implementation of node types (map, convolution, parallel, wfc, etc.)
– src/helpers/* → data structures, I/O readers/writers, symmetry, voxel utilities
• loader: src/loader/index.ts → XML model & rule file parser
• render: src/render/* → abstract/bitmap/isometric/pathtrace renderers, WebGL helper library
• wasm: src/wasm/* → high-performance tasks in WebAssembly (search, observe, optimization) + worker
• native: src/native/* → C headers & compile script producing .wasm for core algorithms
• node: src/node/* → CLI program adapter for Node.js
• web: src/web/* → React components (center/left/right/mobile), state management, index.tsx, HTML template, CSS
• static/
• static/models.xml, static/models/*.xml → model definitions
• static/resources/{palette, rules, samples, tilesets} → assets fed to loader
• Config/build files: webpack.config.js, tsconfig.json, package.json, .github workflows
README for additional insights
• Confirms browser & Node.js targets; heavy computation can be offloaded to WebAssembly.
• Highlights optional “JIT” AssemblyScript → Wasm optimization branch.
• Emphasizes features: isometric rendering, .vox export, node tree visualization.
Main components & interactions
a. Core Engine
• Loader: parses XML models & rules → produces internal graph/rule structures
• Interpreter & Search: executes MarkovJunior algorithm with mj-nodes, helper data structures
• Rule Engine: applies voxel rules, symmetry, pattern constraints
b. WebAssembly Subsystem
• Native C code compiled to .wasm (via compile.sh)
• AssemblyScript “JIT” version (optional optimization branch)
• Wasm modules loaded by src/wasm/index.ts, executed in a WebWorker (src/wasm/worker.ts)
c. Presentation Layer
• Browser UI: React components in src/web render controls & 2D/3D outputs
• Render Engine: WebGL helper lib for isometric/bitmap/pathtrace rendering
• CLI: Node adapter writes .vox files to output directory (src/node/program.ts)
d. Static Asset Server
• Serves static/models, static/resources via webpack dev server or static site build
Relationships & data flows
• User action (UI or CLI) → Loader loads XML → Interpreter invokes Search + Rule modules (possibly via Wasm worker) → produces grid/voxel output → Render Engine visualizes in browser or Writer serializes .vox → Completed result shown or saved
• UI → Core Engine inputs
• Core Engine ↔ Wasm Worker boundary
• Core Engine → Render Engine or Writer
• Static Asset Store → Loader
Architectural patterns & design principles
• Modular separation: Loader / Core / Presentation / WASM / CLI
• Pluggable node graph (mj-nodes directory implements Strategy pattern for each node type)
• Asynchronous boundary: WebWorker / Wasm offloading for CPU-intensive tasks
• Single-page app served by webpack, with dev/prod workflows