# furudean/vscode-renpy-warp architecture

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

- Interactive diagram: https://gitdiagram.com/furudean/vscode-renpy-warp
- Repository: https://github.com/furudean/vscode-renpy-warp

## Overview

##### Project type and purpose
- This is a Visual Studio Code extension (“Ren’Py Launch and Sync”) written in TypeScript whose purpose is to let you launch, warp, and sync a Ren’Py visual-novel game from inside VS Code. It registers commands, spawns a Ren’Py process, and keeps the editor and game in sync via an IPC/RPE protocol.

##### Main components
A. VS Code UI & API
– Command Palette, Editor Context Menu, Explorer Context Menu, Status Bar, Gutter Decorations
– VS Code Extension Host (the runtime for your extension)
B. Extension Modules (inside the Extension Host)
– Activation (`extension.ts`)
– Commands Registry (`lib/commands.ts`)
– Configuration (`lib/config.ts`)
– Handlers (`lib/handlers.ts`)
– Process Management (`lib/process/manager.ts`, `lib/process/index.ts`, `lib/sh.ts`)
– Launch Logic (`lib/launch.ts`)
– RPE Protocol Adapter (`renpy_warp.rpe.py`, `lib/rpe.ts`)
– Socket Communication (`lib/socket.ts`)
– Follow-Cursor Logic (`lib/follow_cursor.ts`)
– Decorations & Status Bar (`lib/decoration.ts`, `lib/status_bar.ts`)
– Label Navigation (`lib/label.ts`)
– Logging (`lib/log.ts`)
– Onboarding Prompt (`lib/onboard.ts`)
– Path Utilities (`lib/path.ts`)
– Window-Focus Utilities (`lib/window.ts`)
C. External Ren’Py Process
– Ren’Py SDK launch (stdin/stdout or IPC)
– RPE‐injected Python helper (`renpy_warp.rpe.py`)

##### Relationships and data flows
1. User triggers a command via VS Code UI → VS Code API calls your Command Registry
2. Command Registry → dispatches to Handlers → consults Config → decides strategy
3. Handler calls Launch or Process Manager → spawns Ren’Py process (shell/`sh.ts`)
4. If using “Update Window” or “Follow Cursor,” extension opens a socket to the RPE helper in the game process
5. Socket ↔ RPE adapter exchange JSON messages (“warp_to_line”, “current_line”)
6. Incoming updates flow back to Handlers → update Editor via VS Code API (move cursor, decorate gutter, update status bar)
7. Logging and onboarding may run in parallel whenever needed

##### Architectural patterns & design principles
- Command–Handler pattern: each VS Code command is wired to a handler that encapsulates logic.
- Modular layering: configuration → command dispatch → process management → IPC → UI update.
- Single responsibility: each module focuses on one concern (e.g., `socket.ts` only manages the socket, `rpe.ts` only formats protocol messages).
- Event-driven IPC: the RPE protocol uses a socket, with callbacks registered on `lib/socket.ts`.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% VS Code UI & API
    subgraph "VS Code UI & API"
        direction TB
        CP["Command Palette"]:::ui
        ECM["Editor Context Menu"]:::ui
        XCM["Explorer Context Menu"]:::ui
        SB["Status Bar"]:::ui
        GD["Gutter Decorations"]:::ui
        UIHost["VS Code Extension Host"]:::ui
    end

    %% Extension Modules
    subgraph "Extension Modules"
        direction TB
        Activation["Activation (extension.ts)"]:::extension
        Commands["Commands Registry (commands.ts)"]:::extension
        Config["Configuration (config.ts)"]:::extension
        Handlers["Handlers (handlers.ts)"]:::extension
        subgraph "Process Management"
            direction TB
            ProcessIndex["Process Index (process/index.ts)"]:::extension
            ProcessMgr["Process Manager (process/manager.ts)"]:::extension
            Shell["Shell Helper (sh.ts)"]:::extension
        end
        Launch["Launch Logic (launch.ts)"]:::extension
        RPETS["RPE Adapter (rpe.ts)"]:::extension
        Socket["Socket Communication (socket.ts)"]:::extension
        Follow["Follow-Cursor Logic (follow_cursor.ts)"]:::extension
        Decoration["Decorations (decoration.ts)"]:::extension
        StatusB["Status Bar (status_bar.ts)"]:::extension
        Label["Label Navigation (label.ts)"]:::extension
        Log["Logging (log.ts)"]:::extension
        Onboard["Onboarding (onboard.ts)"]:::extension
        PathU["Path Utilities (path.ts)"]:::extension
        WindowU["Window Focus Utilities (window.ts)"]:::extension
    end

    %% External Ren'Py Process
    RenPy[("Ren'Py Process\nrenpy_warp.rpe.py")]:::external

    %% Connections: UI to Host
    CP --> UIHost
    ECM --> UIHost
    XCM --> UIHost
    SB --> UIHost
    GD --> UIHost

    %% Host to Extension Activation
    UIHost --> Activation
    Activation --> Commands
    Activation --> Onboard
    Activation --> Config

    %% Command flow
    Commands --> Handlers
    Config --> Handlers

    %% Process spawn flow
    Handlers --> Launch
    Launch --> Shell
    Handlers --> ProcessMgr
    ProcessMgr --> ProcessIndex
    ProcessIndex --> Shell
    Shell --> RenPy

    %% IPC Socket flow
    Handlers --> Socket
    Follow --> Socket
    Socket --> RenPy
    RenPy --> Socket
    Socket --> RPETS
    RPETS --> Handlers

    %% Editor update flow
    Handlers --> Decoration
    Decoration --> GD
    Handlers --> StatusB
    StatusB --> SB
    Handlers --> Label
    Handlers --> Follow
    Handlers --> Log

    %% Utility dependencies
    Config --> PathU
    Handlers --> PathU
    Handlers --> WindowU

    %% Click Events
    click Activation "https://github.com/furudean/vscode-renpy-warp/blob/main/src/extension.ts"
    click Commands "https://github.com/furudean/vscode-renpy-warp/blob/main/src/lib/commands.ts"
    click Config "https://github.com/furudean/vscode-renpy-warp/blob/main/src/lib/config.ts"
    click Handlers "https://github.com/furudean/vscode-renpy-warp/blob/main/src/lib/handlers.ts"
    click ProcessIndex "https://github.com/furudean/vscode-renpy-warp/blob/main/src/lib/process/index.ts"
    click ProcessMgr "https://github.com/furudean/vscode-renpy-warp/blob/main/src/lib/process/manager.ts"
    click Shell "https://github.com/furudean/vscode-renpy-warp/blob/main/src/lib/sh.ts"
    click Launch "https://github.com/furudean/vscode-renpy-warp/blob/main/src/lib/launch.ts"
    click RPETS "https://github.com/furudean/vscode-renpy-warp/blob/main/src/lib/rpe.ts"
    click RenPy "https://github.com/furudean/vscode-renpy-warp/blob/main/src/renpy_warp.rpe.py"
    click Socket "https://github.com/furudean/vscode-renpy-warp/blob/main/src/lib/socket.ts"
    click Follow "https://github.com/furudean/vscode-renpy-warp/blob/main/src/lib/follow_cursor.ts"
    click Decoration "https://github.com/furudean/vscode-renpy-warp/blob/main/src/lib/decoration.ts"
    click StatusB "https://github.com/furudean/vscode-renpy-warp/blob/main/src/lib/status_bar.ts"
    click Label "https://github.com/furudean/vscode-renpy-warp/blob/main/src/lib/label.ts"
    click Log "https://github.com/furudean/vscode-renpy-warp/blob/main/src/lib/log.ts"
    click Onboard "https://github.com/furudean/vscode-renpy-warp/blob/main/src/lib/onboard.ts"
    click PathU "https://github.com/furudean/vscode-renpy-warp/blob/main/src/lib/path.ts"
    click WindowU "https://github.com/furudean/vscode-renpy-warp/blob/main/src/lib/window.ts"

    %% Styles
    classDef ui fill:#add8e6,stroke:#000
    classDef extension fill:#90ee90,stroke:#000
    classDef external fill:#ffcccb,stroke:#000,stroke-width:2px
```
