How birdlogics/sb3topy works
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