# zalo/mujoco_wasm architecture

> Architecture diagram of the GitHub repository zalo/mujoco_wasm, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-01-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zalo/mujoco_wasm
- Repository: https://github.com/zalo/mujoco_wasm

## Overview

##### Key Relationships to Highlight

a. Runtime Flow:
- JavaScript API → WebAssembly Module → Virtual File System
- ↓
- Scene Renderer

b. Build-time Flow:
- Header Files → Parser Scripts → Generated Bindings → Emscripten → WASM Module

##### Specific Implementation Details

a. Core Components:
- Relationship between `mujoco_wasm.js`, `mujoco_wasm.wasm`, and `mujoco_wasm.d.ts`
- Virtual File System mount points
- Model-State-Simulation class hierarchy

b. File Processing:
- XML model loading pipeline
- Asset handling (especially for complex models like shadow_hand and cassie)

- [Browser Environment]
- ↓
- [JavaScript API Layer]
- ↓
- [WebAssembly Module]
- ↓
- [Virtual File System]

##### Technical Details to Emphasize

- The binding layer between JavaScript and C++ (generated code)
- Memory management between JS and WASM
- File system virtualization
- TypeScript type definitions generation
- Build pipeline configuration

##### Important Subsystems

- Header parsing system (`parse_mjxmacro.py`, `ast_nodes.py`)
- Example scene loading mechanism
- Utility modules (Debug.js, DragStateManager.js, Reflector.js)

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph "Runtime Environment"
        Browser["Browser Environment"]
        JSAPI["JavaScript API Layer"]
        WASM["WebAssembly Module"]
        VFS["Virtual File System"]
        Renderer["Scene Renderer/Viewer"]
    end

    subgraph "Build System"
        BuildPipe["CMake Build Pipeline"]
        EmCC["Emscripten Compiler"]
        Parser["Header Parser"]
        Generator["Code Generator"]
        Headers["MuJoCo Headers"]
        GenBindings["Generated Bindings"]
    end

    subgraph "Utility Components"
        Debug["Debug Utils"]
        DragState["Drag State Manager"]
        Reflect["Reflector"]
    end

    subgraph "Example System"
        Scenes["Example Scenes"]
        SceneIndex["Scene Index"]
        MujocoUtils["MuJoCo Utils"]
    end

    %% Runtime Flow
    Browser --> JSAPI
    JSAPI --> WASM
    WASM --> VFS
    WASM --> Renderer
    
    %% Build Flow
    Headers --> Parser
    Parser --> Generator
    Generator --> GenBindings
    GenBindings --> EmCC
    BuildPipe --> EmCC
    EmCC --> WASM

    %% Utility Connections
    Debug --> Renderer
    DragState --> Renderer
    Reflect --> Renderer
    
    %% Example System Connections
    Scenes --> MujocoUtils
    SceneIndex --> MujocoUtils
    MujocoUtils --> JSAPI

    %% Styling
    classDef runtime fill:#e1f5fe,stroke:#01579b
    classDef buildtime fill:#fff3e0,stroke:#ff6f00
    classDef utility fill:#f3e5f5,stroke:#4a148c
    classDef example fill:#e8f5e9,stroke:#1b5e20

    class Browser,JSAPI,WASM,VFS,Renderer runtime
    class BuildPipe,EmCC,Parser,Generator,Headers,GenBindings buildtime
    class Debug,DragState,Reflect utility
    class Scenes,SceneIndex,MujocoUtils example

    %% Click Events
    click JSAPI "https://github.com/zalo/mujoco_wasm/blob/main/dist/mujoco_wasm.js"
    click WASM "https://github.com/zalo/mujoco_wasm/blob/main/dist/mujoco_wasm.wasm"
    click Renderer "https://github.com/zalo/mujoco_wasm/blob/main/examples/main.js"
    click MujocoUtils "https://github.com/zalo/mujoco_wasm/blob/main/examples/mujocoUtils.js"
    click Parser "https://github.com/zalo/mujoco_wasm/blob/main/src/parse_mjxmacro.py"
    click BuildPipe "https://github.com/zalo/mujoco_wasm/blob/main/CMakeLists.txt"
    click Headers "https://github.com/zalo/mujoco_wasm/blob/main/include/mujoco/mujoco.h"
    click GenBindings "https://github.com/zalo/mujoco_wasm/blob/main/src/main.genned.cc"
    click Debug "https://github.com/zalo/mujoco_wasm/blob/main/examples/utils/Debug.js"
    click DragState "https://github.com/zalo/mujoco_wasm/blob/main/examples/utils/DragStateManager.js"
    click Reflect "https://github.com/zalo/mujoco_wasm/blob/main/examples/utils/Reflector.js"
    click Scenes "https://github.com/zalo/mujoco_wasm/tree/main/examples/scenes"
    click SceneIndex "https://github.com/zalo/mujoco_wasm/blob/main/examples/scenes/index.json"
```
