# erdongchen-andrew/charactercontrol architecture

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

- Interactive diagram: https://gitdiagram.com/erdongchen-andrew/charactercontrol
- Repository: https://github.com/erdongchen-andrew/charactercontrol

## Overview

##### Main Components
- User Interface & Demo Layer: Represented by the “example” folder and the “public” directory where assets like 3D models (glb files) and textures reside. This illustrates how the library is used to create interactive 3D scenes.
- Core Library Components: These are the key React components such as:
– Ecctrl.tsx (core character controller)
– EcctrlAnimation.tsx (animation wrapper for the controller)
– EcctrlJoystick.tsx (touch/joystick controls)
- State Management & Hooks: Found in the “src/hooks” and “src/stores” directories. They provide internal state, joystick controls, and other configurations.
- External Integrations: The project relies on external libraries like react‑three‑fiber for rendering and react‑three‑rapier for physics simulation. Also consider integrations with the underlying Three.js library via the public assets.

##### Relationships and Interactions
- The “example” demo uses the exported components to set up a Three.js canvas, applying physics via react‑three‑rapier, and controls via KeyboardControls (and optionally joystick).
- The Ecctrl component acts as the container for the character model. It wraps the character and applies the physics (collision, slopes, jumping, etc.), interacting with the state stores to manage the character’s current state and animations.
- The EcctrlAnimation component further wraps the character model to manage animation states based on user input, while the EcctrlJoystick provides an alternate interface for touch-based controls.
- Hooks and stores are used to share state (for example, current animation, joystick input, or game state) across various components.
- External libraries are shown as input/output nodes that provide canvas rendering, physics calculations, and 3D model loading.

##### Architectural Patterns and Design Principles
- Modular Composition: The components are clearly separated (controller, animation, joystick). This supports a plug‑and‑play design.
- Separation of Concerns: The demo (example) is distinct from the library code (src), while state management is decoupled via hooks and stores.
- Integration of External Systems: Emphasize the layering where react‑three‑fiber renders the scene, react‑three‑rapier supplies physical reactions, and Ecctrl provides enhanced character control logic.
- Configuration & Extensibility: The extensive README and code comments suggest the use of high configurability through props, indicating an API layered design for customization.

##### Relevant Technologies and Frameworks
- React with its component architecture.
- react‑three‑fiber for Three.js encapsulation in React.
- react‑three‑rapier supplying physics features.
- Vite as the bundler and development server (see vite.config.js and vercelVite.config.js).
- Node.js based dependency and build management via package.json.
- Additionally, consider integration with state management libraries as implemented in the “src/stores” folder.

##### What
- Use clear labels for each major part: "Demo UI/Example", "Core Components", "State Management", "Physics Engine Integration", "3D Renderer & Assets".
- Connections to indicate important props passed (e.g., configuration parameters from README) and show the hierarchy (Ecctrl wraps a character model, optionally wrapped by EcctrlAnimation, with parallel input from EcctrlJoystick).

##### Detail Level
- Including notes on configurable parameters as part of the components’ annotations, showing how they modify physics or camera behaviors.

## Diagram (Mermaid)

```mermaid
graph TD
    A["User Input (Keyboard/Joystick)"]:::input

    subgraph "Demo UI/Example & Assets"
        D1["Demo UI/Example"]:::demo
    end

    subgraph "Core Components"
        E1["Ecctrl (Character Controller)"]:::core
        E2["EcctrlAnimation (Animation Wrapper)"]:::core
        E3["EcctrlJoystick (Joystick Controls)"]:::core
    end

    subgraph "State Management"
        S1["useFollowCam"]:::hook
        S2["useGame"]:::store
        S3["useJoystickControls"]:::store
    end

    subgraph "Bundler & Configuration"
        B1["vite.config.js"]:::config
        B2["vercelVite.config.js"]:::config
    end

    subgraph "External Integrations"
        X1["react‑three‑fiber"]:::external
        X2["react‑three‑rapier"]:::external
    end

    A -->|"triggers"| D1
    D1 -->|"initiates"| E1
    E1 -->|"wraps"| E2
    E1 -->|"integrates"| E3
    E1 -->|"readsState"| S2
    E1 -->|"readsState"| S3
    E1 -->|"configBy"| S1
    D1 -->|"renders"| X1
    D1 -->|"physicsCalc"| X2
    E1 -->|"appliesPhysics"| X2
    B1 -->|"builds"| D1
    B1 -->|"builds"| E1
    B2 -->|"builds"| D1
    B2 -->|"builds"| E1

    click D1 "https://github.com/erdongchen-andrew/charactercontrol/blob/main/example/index.tsx"
    click E1 "https://github.com/erdongchen-andrew/charactercontrol/blob/main/src/Ecctrl.tsx"
    click E2 "https://github.com/erdongchen-andrew/charactercontrol/blob/main/src/EcctrlAnimation.tsx"
    click E3 "https://github.com/erdongchen-andrew/charactercontrol/blob/main/src/EcctrlJoystick.tsx"
    click S1 "https://github.com/erdongchen-andrew/charactercontrol/blob/main/src/hooks/useFollowCam.tsx"
    click S2 "https://github.com/erdongchen-andrew/charactercontrol/blob/main/src/stores/useGame.ts"
    click S3 "https://github.com/erdongchen-andrew/charactercontrol/blob/main/src/stores/useJoystickControls.ts"
    click B1 "https://github.com/erdongchen-andrew/charactercontrol/blob/main/vite.config.js"
    click B2 "https://github.com/erdongchen-andrew/charactercontrol/blob/main/vercelVite.config.js"

    classDef input fill:#FFDDC1,stroke:#F08080,stroke-width:2px,color:#000;
    classDef demo fill:#C1FFC1,stroke:#32CD32,stroke-width:2px,color:#000;
    classDef core fill:#C1DFFF,stroke:#1E90FF,stroke-width:2px,color:#000;
    classDef hook fill:#FFFACD,stroke:#DAA520,stroke-width:2px,color:#000;
    classDef store fill:#FFDAB9,stroke:#FF8C00,stroke-width:2px,color:#000;
    classDef config fill:#E6E6FA,stroke:#9370DB,stroke-width:2px,color:#000;
    classDef external fill:#D3D3D3,stroke:#696969,stroke-width:2px,color:#000;
```
