# existancepy/bss-macro-py architecture

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

- Interactive diagram: https://gitdiagram.com/existancepy/bss-macro-py
- Repository: https://github.com/existancepy/bss-macro-py

## Overview

##### Project Type and Purpose
- This is a desktop automation tool (“macro”) for the Bee Swarm Simulator game, written primarily in Python with a small Node.js utility for sprite‐sheet generation and a Tcl/Tk‐based GUI layer.

##### File‐Structure Analysis
- Top‐level:
- macro/ – all Python source code and assets.
- tools/ – OS‐specific command shortcuts for testing.
- README.md, LICENSE, .gitignore – meta.
- macro/ subdirs:
- dataFiles/ – static text config & state files.
- images/, patterns/, paths/ – modular “plugins” for vision patterns and field‐path scripts.
- src/ – front‐end assets for sprite‐sheet generator (Node.js + light/dark themes).
- hourlyReport/ – HTML + Python report generator for periodic status.
- theme/ – Tcl/Tk style sheets for the GUI.
- Key scripts:
- main.py – entry point and coordinator.
- hotkey.py, delay.py, move.py – input abstraction.
- webhook.py – Discord integration.
- update.py, manualupdate.py – self‐update utilities.
- sv.tcl & azure.tcl – Tcl modules to spin up GUI windows via Tk.
- spritesheet_generator.js – Node.js tool to pack images.

##### README Insights
- Confirms feature set: gathering, planters, dispensers, field‐drift/haste compensation, logs, auto‐reconnect, GUI setup, hourly reports, Discord webhook.
- Mentions Mac OS only (Tcl/Tk GUI) and that v1 is deprecated in favor of a v2 rewrite.

##### Diagramming the Architecture
a. Main Components
- User Interface Layer
– Tcl/Tk GUI (sv.tcl, azure.tcl + theme/*.tcl) invoked by Python.
- Core Automation Engine
– main.py orchestrates cycles: read config → iterate fields → call modules.
- Input/Vision Subsystem
– pixelcolour.py + pyscreezeCustom.py + ocrpy.py.
- Action Subsystem
– move.py, delay.py, hotkey.py to issue mouse/keyboard commands.
- Plugin Modules
– paths/ (field scripts), patterns/ (gather strategies), multipliers.txt, etc.
- Configuration & State
– dataFiles/, profiles/, generalsettings.txt, status.txt, logs (macroLogs.log, discord.log).
- Reporting Service
– hourlyReport/generateImg.py + index.html – creates visuals and HTML.
- External Integrations
– Discord Webhook (webhook.py)
– Node.js sprite‐sheet generator (src/spritesheet_generator.js)

b. Relationships & Data Flow
1. User launches the CLI or GUI (sv.tcl invoked via main.py).
2. Core Engine reads profiles & dataFiles → selects which paths/patterns to run.
3. For each cycle, Vision Subsystem captures screen → Action Subsystem issues moves.
4. State updates stored back in dataFiles & logs.
5. At hour boundary, Reporting Service reads logs → generates HTML/images → optionally posts to Discord.
6. Sprite‐sheet generator is a developer/asset‐prep utility, not part of the runtime loop.

c. Architectural Patterns & Principles
- Modular plugin architecture: new field scripts or patterns simply drop into paths/ or patterns/.
- Separation of concerns: Vision, Action, Orchestration, UI, Reporting.
- Single entry point (main.py) routing to submodules via a command pattern.
- Config‐driven: text files + profiles directory govern behavior.

d. Key Technologies & Frameworks
- Python 3.x – core language.
- pyscreeze (with custom fork) – screen capture.
- Tcl/Tk (sv.tcl, azure.tcl) – GUI.
- Node.js & npm – sprite‐sheet generation.
- HTML/CSS/JS – hourlyReport pages.
- Discord Webhooks (HTTP POST).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Interface Layer
    subgraph "User Interface Layer"
        UI_SV["sv.tcl"]:::pythonCore
        UI_AZURE["azure.tcl"]:::pythonCore
        subgraph "Theme Files"
            THEME_DARK["dark.tcl"]:::pythonCore
            THEME_LIGHT["light.tcl"]:::pythonCore
            THEME_SPRITES_DARK["sprites_dark.tcl"]:::pythonCore
            THEME_SPRITES_LIGHT["sprites_light.tcl"]:::pythonCore
        end
    end

    %% Core Automation Engine
    CORE["Core Engine\n(main.py)"]:::pythonCore

    %% Input/Vision Subsystem
    subgraph "Input/Vision Subsystem"
        VISION_OCR["ocrpy.py"]:::pythonCore
        VISION_PIXEL["pixelcolour.py"]:::pythonCore
        VISION_PYSCR["pyscreezeCustom.py"]:::pythonCore
        VISION_IMGSRCH["imagesearch.py"]:::pythonCore
    end

    %% Action Subsystem
    subgraph "Action Subsystem"
        ACTION_MOVE["move.py"]:::pythonCore
        ACTION_DELAY["delay.py"]:::pythonCore
        ACTION_HOTKEY["hotkey.py"]:::pythonCore
    end

    %% Plugin Modules
    subgraph "Plugin Modules"
        PLUG_PATHS["Field Scripts\n(macro/paths/*.py)"]:::plugin
        PLUG_PATTERNS["Gather Patterns\n(macro/patterns/*.py)"]:::plugin
    end

    %% Configuration & State
    subgraph "Configuration & State"
        CFG_DATA["dataFiles/"]:::data
        CFG_PROFILES["profiles/"]:::data
        CFG_SETTINGS["generalsettings.txt"]:::data
        CFG_STATUS["status.txt"]:::data
        CFG_LOG_MACRO["macroLogs.log"]:::data
        CFG_LOG_DISCORD["discord.log"]:::data
        CFG_MULT["multipliers.txt"]:::data
    end

    %% Reporting Service
    subgraph "Reporting Service"
        REP_GEN["generateImg.py"]:::pythonCore
        REP_HTML["index.html"]:::data
    end

    %% External Integrations
    subgraph "External Integrations"
        EXT_DISCORD["Discord Webhook\n(webhook.py)"]:::external
        EXT_SPRITE["Sprite-Sheet Generator\n(spritesheet_generator.js)"]:::external
    end

    %% Relationships
    UI_SV -->|"invoke"| CORE
    UI_AZURE -->|"invoke"| CORE

    CORE -->|"captures"| VISION_OCR
    CORE -->|"captures"| VISION_PIXEL
    CORE -->|"captures"| VISION_PYSCR
    CORE -->|"captures"| VISION_IMGSRCH

    CORE -->|"commands"| ACTION_MOVE
    CORE -->|"commands"| ACTION_DELAY
    CORE -->|"commands"| ACTION_HOTKEY

    CORE -->|"loads plugins"| PLUG_PATHS
    CORE -->|"loads plugins"| PLUG_PATTERNS

    CORE -->|"reads/writes"| CFG_DATA
    CORE -->|"reads/writes"| CFG_PROFILES
    CORE -->|"reads/writes"| CFG_SETTINGS
    CORE -->|"reads/writes"| CFG_STATUS
    CORE -->|"writes"| CFG_LOG_MACRO
    CORE -->|"writes"| CFG_LOG_DISCORD
    CORE -->|"reads"| CFG_MULT

    REP_GEN -->|"reads logs"| CFG_LOG_MACRO
    REP_GEN -->|"reads logs"| CFG_LOG_DISCORD
    REP_GEN -->|"generates"| REP_HTML
    REP_GEN -->|"posts via webhook"| EXT_DISCORD

    %% Developer Utility (not in runtime loop)
    EXT_SPRITE -.->|"asset prep"| PLUG_PATTERNS

    %% Click Events
    click UI_SV "https://github.com/existancepy/bss-macro-py/blob/main/macro/sv.tcl"
    click UI_AZURE "https://github.com/existancepy/bss-macro-py/blob/main/macro/azure.tcl"
    click THEME_DARK "https://github.com/existancepy/bss-macro-py/blob/main/macro/theme/dark.tcl"
    click THEME_LIGHT "https://github.com/existancepy/bss-macro-py/blob/main/macro/theme/light.tcl"
    click THEME_SPRITES_DARK "https://github.com/existancepy/bss-macro-py/blob/main/macro/theme/sprites_dark.tcl"
    click THEME_SPRITES_LIGHT "https://github.com/existancepy/bss-macro-py/blob/main/macro/theme/sprites_light.tcl"
    click CORE "https://github.com/existancepy/bss-macro-py/blob/main/macro/main.py"
    click VISION_OCR "https://github.com/existancepy/bss-macro-py/blob/main/macro/ocrpy.py"
    click VISION_PIXEL "https://github.com/existancepy/bss-macro-py/blob/main/macro/pixelcolour.py"
    click VISION_PYSCR "https://github.com/existancepy/bss-macro-py/blob/main/macro/pyscreezeCustom.py"
    click VISION_IMGSRCH "https://github.com/existancepy/bss-macro-py/blob/main/macro/imagesearch.py"
    click ACTION_MOVE "https://github.com/existancepy/bss-macro-py/blob/main/macro/move.py"
    click ACTION_DELAY "https://github.com/existancepy/bss-macro-py/blob/main/macro/delay.py"
    click ACTION_HOTKEY "https://github.com/existancepy/bss-macro-py/blob/main/macro/hotkey.py"
    click PLUG_PATHS "https://github.com/existancepy/bss-macro-py/tree/main/macro/paths/"
    click PLUG_PATTERNS "https://github.com/existancepy/bss-macro-py/tree/main/macro/patterns/"
    click CFG_DATA "https://github.com/existancepy/bss-macro-py/tree/main/macro/dataFiles/"
    click CFG_PROFILES "https://github.com/existancepy/bss-macro-py/tree/main/macro/profiles/"
    click CFG_SETTINGS "https://github.com/existancepy/bss-macro-py/blob/main/macro/generalsettings.txt"
    click CFG_STATUS "https://github.com/existancepy/bss-macro-py/blob/main/macro/status.txt"
    click CFG_LOG_MACRO "https://github.com/existancepy/bss-macro-py/blob/main/macro/macroLogs.log"
    click CFG_LOG_DISCORD "https://github.com/existancepy/bss-macro-py/blob/main/macro/discord.log"
    click CFG_MULT "https://github.com/existancepy/bss-macro-py/blob/main/macro/multipliers.txt"
    click REP_GEN "https://github.com/existancepy/bss-macro-py/blob/main/macro/hourlyReport/generateImg.py"
    click REP_HTML "https://github.com/existancepy/bss-macro-py/blob/main/macro/hourlyReport/index.html"
    click EXT_DISCORD "https://github.com/existancepy/bss-macro-py/blob/main/macro/webhook.py"
    click EXT_SPRITE "https://github.com/existancepy/bss-macro-py/blob/main/macro/src/spritesheet_generator.js"

    %% Styles
    classDef pythonCore fill:#D0E8FF,stroke:#000,stroke-width:1px
    classDef plugin fill:#E2F0D0,stroke:#000,stroke-width:1px
    classDef external fill:#FFE2B3,stroke:#000,stroke-width:1px
    classDef data fill:#E0E0E0,stroke:#000,stroke-width:1px
```
