# renpy/renpyweb architecture

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

- Interactive diagram: https://gitdiagram.com/renpy/renpyweb
- Repository: https://github.com/renpy/renpyweb

## Overview

##### Main Components

- Build & Patch Infrastructure:
- Makefile, patch directories (patches, python-emscripten/…/patches, etc.)
- Scripts in the "scripts" folder for tasks like compiling libraries (SDL2, ffmpeg, libpng, etc.), cleaning, and packaging.
- This component is responsible for configuring the build process, applying patches to both Python’s source files (e.g., ceval.c, importexport.c) and Ren’Py-specific code.

- Emscripten Integration Layer:
- The “python-emscripten” directory holds several Python versions (2.7.10, 2.7.18, 3.8) customized for building with Emscripten.
- Files like emscripten.pyx and webprompt-related scripts (webprompt.sh, webprompt-main.c) illustrate the integration of Python’s interpreter with Emscripten.
- This layer converts the C/Python-based engine into JavaScript/WebAssembly suitable for browser execution.

- Core Interpreter and Engine Components:
- C source files such as main.c, ceval.c, and importexport.c likely represent the modified Python interpreter core and interfaces needed by Ren’Py.
- The integration with Ren’Py elements may be represented by headers or additional source linking, even if implicit.

- Ren’Py Web Runtime:
- “renpy-pre.js”, “renpy-shell.html”, and the “pygame-example*” files indicate the front-end web components.
- These files are used to bootstrap the compiled engine in the browser, handling user interactions and display.
- There’s also integration with basic test pages and a test server (make testserver) for local debugging.

- Testing and Example Modules:
- The “tests” directory and “pygame-example” folder provide sample scenarios and tests to validate the build and functionality.
- These components are essential for verifying that the patches, compilation, and runtime execute correctly in the target environment.

##### Establish Relationships and Data/Control Flow

- The Build & Patch Infrastructure feeds into the Emscripten Integration Layer. The Makefile, along with the scripts, runs a series of tasks:
- Applying patches to the Python interpreter and game engine source.
- Using Emscripten (emcc and related tools) to compile these sources into a web-ready format.

- The Emscripten Integration Layer creates a binary (or WebAssembly/JavaScript module) that encapsulates the core interpreter/engine.
- This module is then embedded within the Ren’Py web runtime, which provides a user interface via HTML and JavaScript.

- The Runtime communicates with the client’s web browser:
- “renpy-shell.html” and “pygame-example-shell.html” serve as entry points.
- The test server (triggered via “make testserver”) is used during development for live testing in the browser.

- Testing components (in “tests” and example modules) simulate game scenarios ensuring different aspects (audio, threading, rendering, etc.) perform as expected.

##### Architectural Patterns and Design Principles

- Modularity: Separation between build scripts, patches, core interpreter, and runtime interface clearly demarcates the system components.
- Layered Architecture: There is a layer for native code (C source & Python interpreter), one for compilation (Emscripten integration), and another for web presentation (HTML/JS runtime).
- Cross-compilation emphasis: The system is designed to recompile and patch various Python versions to support the specific constraints of the web environment.

##### Instructing the Principal Software Engineer

- Initiation from the Makefile (triggered command) along with scripts that manage dependencies (such as SDL2.sh, ffmpeg.sh, etc.).
- Detail the Emscripten integration:
- How the patched Python interpreter (with files like ceval.c and others) is fed into Emscripten, which then produces the JavaScript/WebAssembly module.
- Detail the runtime side:
- How web files (renpy-shell.html, renpy-pre.js, pygame-example HTML/JS) interact with the compiled module, and how a test server provides a local development environment.
- Testing and utility sub-systems:
- Role of the tests directory and individual test scripts that validate both engine functionality and browser interactivity.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Build & Patch Infrastructure"
      MF("Makefile"):::build
      P("Patches"):::build
      S("Scripts"):::build
    end

    subgraph "Core Interpreter and Engine Components"
      C1("ceval.c"):::core
      C2("importexport.c"):::core
      C3("main.c"):::core
    end

    subgraph "Emscripten Integration Layer"
      PE("python-emscripten"):::integration
      EP("emscripten.pyx"):::integration
      WM("webprompt-main.c"):::integration
      WH("webprompt-shell.html"):::integration
    end

    subgraph "Ren’Py Web Runtime"
      RP("renpy-pre.js"):::runtime
      RS("renpy-shell.html"):::runtime
      PEX("pygame-example-shell.html"):::runtime
      PX("pygame-example"):::runtime
    end

    subgraph "Testing & Example Modules"
      T("tests"):::testing
      TS("testserver.py"):::testing
    end

    %% Build & Patch Infrastructure -> Core Interpreter
    MF -->|"runs"| S
    MF -->|"triggers"| P
    S -->|"patches"| C1
    S -->|"patches"| C2
    S -->|"patches"| C3
    P -->|"supplies"| C1
    P -->|"supplies"| C2
    P -->|"supplies"| C3

    %% Core Interpreter -> Emscripten Integration Layer
    C1 -->|"compiled"| PE
    C2 -->|"compiled"| PE
    C3 -->|"compiled"| PE

    %% Internal flow within Emscripten Integration Layer
    PE -->|"includes"| EP
    PE -->|"includes"| WM
    PE -->|"includes"| WH
    PE -->|"produces module"| RS

    %% Emscripten Integration -> Runtime specifics
    EP -->|"injects"| RP
    WM -->|"embedded in"| PEX
    WH -->|"loaded by"| RS

    %% Runtime and Testing interactions
    RP -->|"initializes"| RS
    RS -->|"served by"| TS
    PX -->|"provides examples to"| RS
    PX -->|"validated by"| T

    %% Styling definitions
    classDef build fill:#ffcccc,stroke:#cc0000,stroke-width:2px;
    classDef core fill:#ccffcc,stroke:#009900,stroke-width:2px;
    classDef integration fill:#ccccff,stroke:#0000cc,stroke-width:2px;
    classDef runtime fill:#ffffcc,stroke:#999900,stroke-width:2px;
    classDef testing fill:#ffebcc,stroke:#ff6600,stroke-width:2px;

    %% Click Events for Build & Patch Infrastructure
    click MF "https://github.com/renpy/renpyweb/tree/master/Makefile"
    click P "https://github.com/renpy/renpyweb/tree/master/patches/"
    click S "https://github.com/renpy/renpyweb/tree/master/scripts/"

    %% Click Events for Emscripten Integration Layer
    click PE "https://github.com/renpy/renpyweb/tree/master/python-emscripten/"
    click EP "https://github.com/renpy/renpyweb/blob/master/python-emscripten/emscripten.pyx"
    click WM "https://github.com/renpy/renpyweb/blob/master/python-emscripten/webprompt-main.c"
    click WH "https://github.com/renpy/renpyweb/blob/master/python-emscripten/webprompt-shell.html"

    %% Click Events for Core Interpreter and Engine Components
    click C1 "https://github.com/renpy/renpyweb/blob/master/ceval.c"
    click C2 "https://github.com/renpy/renpyweb/blob/master/importexport.c"
    click C3 "https://github.com/renpy/renpyweb/blob/master/main.c"

    %% Click Events for Ren’Py Web Runtime
    click RP "https://github.com/renpy/renpyweb/blob/master/renpy-pre.js"
    click RS "https://github.com/renpy/renpyweb/blob/master/renpy-shell.html"
    click PEX "https://github.com/renpy/renpyweb/blob/master/pygame-example-shell.html"
    click PX "https://github.com/renpy/renpyweb/tree/master/pygame-example/"

    %% Click Events for Testing and Example Modules
    click T "https://github.com/renpy/renpyweb/tree/master/tests/"
    click TS "https://github.com/renpy/renpyweb/blob/master/testserver.py"
```
