How existancepy/bss-macro-py-experimental works
Project type and purpose
• This is a desktop automation “macro” tool written in Python that drives the Roblox Bee Swarm Simulator game on macOS/Windows.
• It provides a local web-based GUI, a core macro engine, and a collection of functional modules (gathering, collecting, killing, planters, boosts), plus reporting and Discord integration.
Main components
a. Frontend (UI)
• src/webapp: static HTML/CSS/JS assets, loaded by gui.py or a minimal HTTP server.
• gui.py / main.py: bootstrap the UI, serve or open index.html in a browser/webview.
b. Backend / Core Engine
• src/main.py: orchestrates startup, loads settings, dispatches user commands to the macro subsystem.
• src/modules/macro.py: high-level macro logic, invokes submacros.
c. Modules (Business Logic)
• controls: keyboard.py, mouse.py, sleep.py → simulate input & timing.
• screen: screenshot.py, imageSearch.py, OCR, pixelColor → read game state.
• misc: settingsManager.py, appManager.py, update.py, imageManipulation.py, messageBox.py → utilities and OS integration.
• logging: log.py, webhook.py → local logs and optional webhook pushes.
• discord_bot: discordBot.py → push status/messages to a Discord server.
• submacros: gathering patterns, memoryMatch, walk, backpack, etc.
d. Data & Configuration
• settings/: user-provided paths, patterns, profiles (.py, .txt, .workflow).
• src/data/: built-in default settings, user data files.
• src/images/: reference images for GUI assets or image recognition.
e. Reporting
• src/hourly_report: static HTML pages, JavaScript/CSS, produces hourly snapshots.
f. External Services
• Discord API (via discord_bot)
• (optionally) Webhooks (via logging/webhook.py)
• Local OS services (AppleScript on macOS, window management)
Relationships & Data Flow
• The user interacts with the Web UI → GUI sends commands (e.g., “start gather”) to main.py.
• main.py forwards commands to the macro engine → macro.py.
• macro.py invokes the appropriate submacro(s) → submacros/*.py.
• Submacros coordinate:
• screen module to inspect game state,
• controls module to send keyboard/mouse events,
• misc module for timing and OS calls.
• All events and errors are routed through the logging module.
• Optionally, the discord_bot reports status updates to a Discord channel.
• The hourly_report component can be triggered by a scheduler or the user to generate HTML output from data in src/data and settings.
Architectural patterns & design principles
• Modular Separation of Concerns: each domain (controls, vision, logging, Discord, submacros) lives in its own namespace.
• MVC-style split:
• Model = settings + data files,
• View = webapp frontend,
• Controller = main.py + macro.py + modules.
• Plugin-like extensibility: new paths/patterns/submacros can be dropped into settings/ or modules/submacros.
• Single source of truth for settings: settingsManager.py loads both default and user overrides.