# mrcatplay/blockbot architecture

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

- Interactive diagram: https://gitdiagram.com/mrcatplay/blockbot
- Repository: https://github.com/mrcatplay/blockbot

## Overview

##### Project type and purpose
- This is a Node.js-based code generator for CtrlBots scripting.

##### File structure
- index.js – the entry point that pulls everything together.
- function/
- event/ – modules modeling each type of event node (Window.js, death.js, end.js, eventlist.js, message.js).
- variable/ – EditVariable.js handles “cloud” variable nodes.
- package.json / package-lock.json – Node.js dependencies and scripts.

##### README for additional insights
- The README describes the domain (CtrlBots events, commands, variables) and how users create scripts by placing blocks.

a. Main components
1. Input Layer
– index.js CLI or import
2. Graph Parsing Layer
– searchInDrawioFile.js: reads and locates all nodes
– findConnections.js: identifies edges between nodes
3. Graph Traversal & Interpretation
– dfs.js: depth-first traversal of the node graph
– handleConnectionAction.js: triggers appropriate node handlers as edges are followed
4. Node Handlers
– eventMessager.js: maps event nodes to bot-script event calls
– variables.js & EditVariable.js: manage variable definition, operations, and injection into script
– function/event/*.js: specific event modules (Window, death, end, etc.)
5. Output Generation
– index.js collects processed nodes and writes final CtrlBots script (or JSON)
6. Execution Environment
– CtrlBots engine that will run the generated script in the game

b. Relationships and interactions
- Parsing Layer produces a node+edge representation passed to the Traversal & Interpretation.
- During traversal, each node is dispatched to a handler (event or variable).
- Handlers emit fragments of bot‐script.
- Output Generator stitches those fragments into a complete script.

c. Architectural patterns / design principles
- Modular handlers: each node type (event, variable) has its own module.
- Separation of concerns: parsing vs. traversal vs. code‐generation.
- Graph‐based processing: explicit DFS over node graph.
- Pluggable: new event/command types can be added by dropping a new handler in function/event or function/variable.

d. Key technologies
- Node.js for orchestration.
- XML parsing (built-in or via a library you include in searchInDrawioFile.js).
- Plain-JS modules for each block type.

##### Detailed capture of essential architecture
- For each layer, break out its sub-components (e.g., under “Node Handlers” show eventMessager.js, variables.js, EditVariable.js, each event/*.js).
- Modular addition point: “Drop new .js in function/event or function/variable to extend”.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Top: External Tools
    User["User"]:::external
    DrawIO["Draw.io Editor"]:::external
    User -->|design blocks| DrawIO

    %% Input Layer
    subgraph "Input Layer"
        ScriptDI["script.drawio"]:::artifact
        Index["Index.js CLI"]:::service
    end
    DrawIO -->|"exports XML"| ScriptDI
    ScriptDI -->|".readFile()"| Index

    %% Graph Parsing Layer
    subgraph "Graph Parsing Layer"
        Search["Parser: searchInDrawioFile.js"]:::parser
        FindConn["Parser: findConnections.js"]:::parser
    end
    Index -->|"parseXML()"| Search
    Search -->|"findAllNodes()"| FindConn

    %% Graph Traversal & Interpretation
    subgraph "Traversal & Interpretation"
        DFS["DFS: dfs.js"]:::parser
        HandleConn["Handler: handleConnectionAction.js"]:::parser
    end
    FindConn -->|"findConnections()"| DFS
    DFS -->|"dfsTraverse()"| HandleConn

    %% Node Handlers
    subgraph "Node Handlers"
        EventMsg["Event Mapper: eventMessager.js"]:::handler
        Vars["Variable Manager: variables.js"]:::handler
        EditVar["Cloud Variable Editor: EditVariable.js"]:::handler
        subgraph "Event Modules"
            WinEvt["Window Event: Window.js"]:::module
            DeathEvt["Death Event: death.js"]:::module
            EndEvt["End Event: end.js"]:::module
            ListEvt["Event List: eventlist.js"]:::module
            MsgEvt["Message Event: message.js"]:::module
        end
    end
    HandleConn -->|"handleAction()"| EventMsg
    HandleConn -->|"handleAction()"| Vars
    HandleConn -->|"handleAction()"| EditVar
    HandleConn -->|"dispatch()"| WinEvt
    HandleConn -->|"dispatch()"| DeathEvt
    HandleConn -->|"dispatch()"| EndEvt
    HandleConn -->|"dispatch()"| ListEvt
    HandleConn -->|"dispatch()"| MsgEvt

    %% Output Generation
    subgraph "Output Generation"
        Generated["Generated CtrlBots Script"]:::output
    end
    EventMsg -->|"emitEventCall()"| Generated
    Vars -->|"manageVar()"| Generated
    EditVar -->|"injectVar()"| Generated
    WinEvt & DeathEvt & EndEvt & ListEvt & MsgEvt -->|"emitScriptFragment()"| Generated
    Generated -->|"writeFile()"| Index

    %% Execution Environment
    BotEngine["CtrlBots Engine"]:::external
    Generated -->|"runScript()"| BotEngine

    %% Project Configuration
    subgraph "Configuration"
        Pkg["package.json"]:::config
        PkgLock["package-lock.json"]:::config
    end
    Index -.-> Pkg
    Index -.-> PkgLock

    %% Click Events
    click ScriptDI "https://github.com/mrcatplay/blockbot/blob/main/script.drawio"
    click Index "https://github.com/mrcatplay/blockbot/blob/main/index.js"
    click Search "https://github.com/mrcatplay/blockbot/blob/main/function/draw/searchInDrawioFile.js"
    click FindConn "https://github.com/mrcatplay/blockbot/blob/main/function/draw/findConnections.js"
    click DFS "https://github.com/mrcatplay/blockbot/blob/main/function/draw/dfs.js"
    click HandleConn "https://github.com/mrcatplay/blockbot/blob/main/function/draw/handleConnectionAction.js"
    click EventMsg "https://github.com/mrcatplay/blockbot/blob/main/function/draw/eventMessager.js"
    click Vars "https://github.com/mrcatplay/blockbot/blob/main/function/draw/variables.js"
    click EditVar "https://github.com/mrcatplay/blockbot/blob/main/function/variable/EditVariable.js"
    click WinEvt "https://github.com/mrcatplay/blockbot/blob/main/function/event/Window.js"
    click DeathEvt "https://github.com/mrcatplay/blockbot/blob/main/function/event/death.js"
    click EndEvt "https://github.com/mrcatplay/blockbot/blob/main/function/event/end.js"
    click ListEvt "https://github.com/mrcatplay/blockbot/blob/main/function/event/eventlist.js"
    click MsgEvt "https://github.com/mrcatplay/blockbot/blob/main/function/event/message.js"
    click Pkg "https://github.com/mrcatplay/blockbot/blob/main/package.json"
    click PkgLock "https://github.com/mrcatplay/blockbot/blob/main/package-lock.json"

    %% Styles
    classDef external fill:#dddddd,stroke:#888888,color:#333333,stroke-width:1px,shape:parallelogram
    classDef artifact fill:#ffffff,stroke:#0088cc,color:#0088cc,stroke-width:2px
    classDef service fill:#cce5ff,stroke:#3399ff,color:#005cbf,stroke-width:2px
    classDef parser fill:#d4edda,stroke:#28a745,color:#155724,stroke-width:2px
    classDef handler fill:#fff3cd,stroke:#ffc107,color:#856404,stroke-width:2px
    classDef module fill:#e2e3e5,stroke:#6c757d,color:#343a40,stroke-width:2px
    classDef output fill:#fde2e4,stroke:#fa5252,color:#c92a2a,stroke-width:2px
    classDef config fill:#f8f9fa,stroke:#6c757d,color:#495057,stroke-width:1px,stroke-dasharray: 2 2
```
