# birdlogics/sb3topy architecture

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

- Interactive diagram: https://gitdiagram.com/birdlogics/sb3topy
- Repository: https://github.com/birdlogics/sb3topy

## Overview

##### Project Type and Purpose
- This is a command-line and GUI tool (“sb3topy”) for converting Scratch 3.0 (.sb3) projects into runnable Python code, plus an accompanying Python-based game engine (using Pygame) to execute the converted code.
- Key indicators:
- README describes converting Scratch projects → Python & running via sb3topy engine
- File tree splits into two major areas: “src/engine” (the runtime) and “src/sb3topy” (the converter CLI/GUI)

##### File Structure Analysis
- Top-level:
- run_gui.pyw, run_main.py – entry points for GUI and CLI
- requirements.txt – external deps (pygame, requests, cairosvg)
- src/engine:
- Core engine modules: runtime, render, events, operators, user_input, util, config, plus a “types” subpackage (costumes, lists, pen, sounds, target)
- src/sb3topy:
- CLI entry (main.py, __main__.py)
- config: JSON defaults, consts, project settings
- gui: application window, convert/run buttons, settings, sidebar, examples
- unpacker: download sb3, extract assets, convert SVG → PNG
- parser: naming, sanitization, block→Python mapping (specmap), AST construction
- packer: bundle generated Python, copy engine files into output directory
- tests: simple test for sanitization logic

##### README Insights
- Conversion pipeline: download/extract sb3 → parse blocks → generate Python + copy engine → optionally run
- GUI orchestrates same pipeline behind the scenes; CLI can be used headlessly
- External tools: requests (to fetch remote projects), cairosvg or Inkscape for SVG conversion, Pygame for running converted projects

a. Main Components
- User Interfaces: CLI (run_main) and GUI (run_gui)
- Unpacker Module
- Parser Module
- Packer Module
- Engine Module (runtime, render, events, operators, user_input, types, util, config)
- External Services/Tools: Scratch .sb3 archive, HTTP endpoints, SVG converters (CairoSVG/Inkscape), Pygame runtime
- File System / Output Directory

b. Relationships & Data Flows
1. User invokes CLI or GUI
2. The UI calls Unpacker → extracts sb3 archive → raw assets (JSON project data, images, sounds)
3. Parser reads project JSON and assets → uses specmap to map blocks to Python AST → outputs Python code snippet per target
4. Packer collects generated code + engine files → writes final .py script + assets to OUTPUT_DIR
5. If “–run” flag or GUI “Run” clicked → imports engine.runtime → executes project via Pygame
6. Engine modules interact at runtime: runtime drives events → user_input → operators → render frames

c. Architectural Patterns & Principles
- Layered Pipeline: Unpack → Parse → Pack → Execute
- Modular Separation: each stage in its own package
- Configuration-driven: config defaults loaded, overrides via CLI/GUI settings
- Extension points: specmap data files can be updated to support new blocks

d. Key Technologies & Frameworks
- Python 3.7+; stdlib modules (json, zipfile, importlib)
- Pygame (rendering, audio, input)
- requests (HTTP download)
- cairosvg / Inkscape (SVG → PNG)
- PyInstaller-style file copy for engine runtime

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Input Sources
    ScratchArchive[".sb3 file"]:::external
    HTTP["Project URL (HTTP)"]:::external

    %% User Interfaces
    subgraph "User Interfaces"
        CLI["CLI Interface"]:::ui
        GUI["GUI Interface"]:::ui
    end

    %% Pipeline Modules
    subgraph "Conversion Pipeline"
        Unpacker["Unpacker Module"]:::pipeline
        Assets["Assets: JSON, images, sounds"]:::data
        Parser["Parser Module"]:::pipeline
        Code["Generated Python Code (AST→.py)"]:::data
        Packer["Packer Module"]:::pipeline
        ConfigFiles["Configuration Files"]:::config
    end

    %% Output & Execution
    Output["Output: Python script + assets"]:::external
    Runtime["Engine Runtime"]:::engine

    %% Engine Internals
    subgraph "Engine Module"
        direction TB
        RuntimeCore["runtime"]:::engine
        Events["events"]:::engine
        Operators["operators"]:::engine
        Render["render"]:::engine
        UserInput["user_input"]:::engine
        Util["util"]:::engine
        EngineConfig["config"]:::engine
        subgraph "types"
            Costumes["costumes"]:::engine
            Lists["lists"]:::engine
            Pen["pen"]:::engine
            Sounds["sounds"]:::engine
            Target["target"]:::engine
        end
    end

    %% External Tools
    SVGTools["SVG Converters\n(CairoSVG/Inkscape)"]:::external

    %% Flows
    ScratchArchive --> CLI
    HTTP --> CLI
    ScratchArchive --> GUI
    HTTP --> GUI

    CLI --> Unpacker
    GUI --> Unpacker

    SVGTools --> Unpacker
    Unpacker --> Assets
    Assets --> Parser
    Parser --> Code
    Code --> Packer
    ConfigFiles --> Packer
    Packer --> Output

    Output -->|"--run or GUI Run"| RuntimeCore

    RuntimeCore --> Events
    Events --> Operators
    Operators --> Render
    Render --> RuntimeCore
    RuntimeCore --> UserInput
    RuntimeCore --> Util
    RuntimeCore --> EngineConfig
    RuntimeCore --> Costumes
    RuntimeCore --> Lists
    RuntimeCore --> Pen
    RuntimeCore --> Sounds
    RuntimeCore --> Target

    %% Click Events
    click CLI "https://github.com/birdlogics/sb3topy/blob/main/src/run_main.py"
    click CLI "https://github.com/birdlogics/sb3topy/blob/main/src/sb3topy/main.py"
    click CLI "https://github.com/birdlogics/sb3topy/blob/main/src/sb3topy/__main__.py"
    click GUI "https://github.com/birdlogics/sb3topy/blob/main/src/run_gui.pyw"
    click GUI "https://github.com/birdlogics/sb3topy/blob/main/src/sb3topy/gui/app.py"
    click Unpacker "https://github.com/birdlogics/sb3topy/tree/main/src/sb3topy/unpacker"
    click Parser "https://github.com/birdlogics/sb3topy/tree/main/src/sb3topy/parser"
    click Packer "https://github.com/birdlogics/sb3topy/blob/main/src/sb3topy/packer/packer.py"
    click ConfigFiles "https://github.com/birdlogics/sb3topy/blob/main/src/sb3topy/config/config.json"
    click RuntimeCore "https://github.com/birdlogics/sb3topy/blob/main/src/engine/runtime.py"
    click Events "https://github.com/birdlogics/sb3topy/blob/main/src/engine/events.py"
    click Render "https://github.com/birdlogics/sb3topy/blob/main/src/engine/render.py"
    click Operators "https://github.com/birdlogics/sb3topy/blob/main/src/engine/operators.py"
    click UserInput "https://github.com/birdlogics/sb3topy/blob/main/src/engine/user_input.py"
    click Util "https://github.com/birdlogics/sb3topy/blob/main/src/engine/util.py"
    click EngineConfig "https://github.com/birdlogics/sb3topy/blob/main/src/engine/config.py"
    click Costumes "https://github.com/birdlogics/sb3topy/blob/main/src/engine/types/costumes.py"
    click Lists "https://github.com/birdlogics/sb3topy/blob/main/src/engine/types/lists.py"
    click Pen "https://github.com/birdlogics/sb3topy/blob/main/src/engine/types/pen.py"
    click Sounds "https://github.com/birdlogics/sb3topy/blob/main/src/engine/types/sounds.py"
    click Target "https://github.com/birdlogics/sb3topy/blob/main/src/engine/types/target.py"
    click Assets "https://github.com/birdlogics/sb3topy/blob/main/src/sb3topy/unpacker/extract.py"
    click Code "https://github.com/birdlogics/sb3topy/blob/main/src/sb3topy/parser/specmap/blockmap.py"

    %% Styles
    classDef ui fill:#add8e6,stroke:#000
    classDef pipeline fill:#90ee90,stroke:#000
    classDef engine fill:#ffa500,stroke:#000
    classDef external fill:#d3d3d3,stroke:#000
    classDef data fill:#f0e68c,stroke:#000
    classDef config fill:#fffacd,stroke:#000
```
