How gabrielagrela/osrokbot works
Project Type and Purpose
• OSROKBOT is an open-source automation tool (not a web or full-stack application) written in Python. Its purpose is to automate gameplay in “Rise of Kingdoms” by using image detection and state machines to perform predefined in-game actions (e.g., farming, scouting, captcha detection).
High-Level Architectural Components
a. Core Orchestrator
• OS_ROKBOT.py: the entry point that loads configuration, initializes the UI (if any), sets up state machines, and starts the automation loop.
b. State Machine Subsystem
• state_machine.py: defines the finite state machine (FSM) engine.
• action_sets.py: collections of named sequences of Actions forming distinct workflows (farm barbs, farm rss, lyceum, captcha detection).
c. Actions Subsystem
• Classes/Actions/*.py: each file implements a concrete Action class (e.g., find_and_click_image, press_key, email_action, chatgpt_action).
• action.py: base class / interface for all Actions.
d. Image Detection & OCR
• image_finder.py: wraps OpenCV template-matching logic for screenshot pattern matching.
• helpers.py: common image preprocessing (e.g., resizing, grayscale conversion) and utility functions.
• Requires external Tesseract binary for OCR (extract_text_action.py).
e. Window & Input Handling
• window_handler.py: captures screenshots of the game window, moves/clicks mouse, sends keystrokes.
• signal_emitter.py: event bus for decoupling input events and action completion signals.
f. UI & Configuration
• UI.py: optional command-line or minimal GUI interface to select which action_set to run.
• global_vars.py: shared configuration values (paths, thresholds, env variables).
• .env file (user‐provided) for API keys, email credentials, Tesseract path.
g. External Services
• OpenAI ChatGPT API (chatgpt_action.py).
• SMTP Email server (email_action.py).
• Tesseract OCR engine.
h. Media & Assets
• Media/UI: reference screenshots used for matching.
• roklyceum.csv: data file containing question/answer mapping for the Lyceum event.
Relationships & Data Flow
1. OS_ROKBOT.py reads .env → initializes global_vars → loads action_sets.
2. User selects workflow via UI.py (or CLI flags).
3. Core loop: state_machine invokes current Action.
4. Action (e.g., find_and_click_image) calls image_finder and window_handler:
• image_finder grabs screenshot from window_handler → runs template match → returns coordinates.
• window_handler moves mouse/clicks at returned coords.
• OCR Actions call Tesseract via subprocess on screenshots.
5. Action returns success/failure → state_machine transitions to next state.
6. Special Actions (chatgpt_action, email_action) call external APIs.
7. Loop continues until final state or quit_action is reached.
Architectural Patterns & Design Principles
• Modular plugin-style Actions adhering to a common interface (action.py) & discoverable via action_sets.
• Explicit FSM pattern for workflow management.
• Separation of concerns: image detection, input handling, business logic (actions), orchestration (state_machine).
• Dependency injection via global_vars and signal_emitter for loose coupling.
• Extensibility: new Actions and state_machines can be dropped into Classes/Actions and action_sets.py.
Detail Level
• How action_sets.py ties specific Action classes into named workflows.
• How signal_emitter decouples UI input events from automation logic.