How existancepy/bss-macro-py works
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).