How zenpaiang/wos-bot works
Project type and purpose
• This is a Python-based Discord utility bot (wos-bot) for “Whiteout Survival” giftcode redemption, captcha detection (via an ONNX OCR model), and various in-game utility commands.
• It follows a modular “cogs” pattern on top of a Discord interactions library and uses JSON files for persistent storage.
File structure
• Top-level:
• bot.py – entry point that spins up the Discord client and loads cogs.
• config.example.json / players.example.json – sample configuration + user database.
• requirements.txt – Python dependencies (including ddddocr).
• migration_tool.py – stand-alone script to migrate v1 player data.
• commands_and_features.md – human-readable feature list.
• “cogs/” directory: each file (calculate.py, database.py, giftcode.py, settings.py) implements a distinct slash-command category.
• “lib/” directory: core shared services (api.py for external calls, cfg.py for config loading, client.py for the Discord client wrapper, funcs.py for utility functions).
• “database/” directory: JSON files storing game data (e.g., chief_charm.json, fire_crystals.json).
• players.json (runtime) – file-based store for linked Discord users.
Key insights from README
• Uses onnx-based OCR (~50 MB) for captcha; no GPU requirement.
• Configuration values control admin locks, auto-rename, syncing features.
• Migration tool handles data upgrade from v1.
a. Main components:
• Discord Gateway & Events (external service)
• Bot Core (bot.py + lib/client.py)
• Cog Modules (cogs/)
• OCR Service (ddddocr ONNX model)
• Persistence Layer (JSON files: players.json + database/*.json)
• Migration Tool (migration_tool.py)
b. Relationships & interactions:
1. Discord Gateway → Bot Core: incoming events (slash-commands, messages).
2. Bot Core → Cog Modules: dispatch events to relevant command handlers.
3. Cog Modules → Lib Services:
• cfg.py loads config.json
• api.py calls external game APIs if needed
• funcs.py for shared logic (e.g., parsing giftcodes)
4. OCR Service: invoked by giftcode cog to solve captchas.
5. Cog Modules → Persistence Layer: read/write players.json and game-data JSONs.
6. Migration Tool (offline) → Persistence Layer: upgrades old players.json schema.
c. Architectural patterns & design principles:
• Modular “cogs” plugin pattern for commands
• Separation of concerns: CLI / config loader / API / utility functions in lib/
• File-based lightweight persistence (no DB server)
• Single process, event-driven architecture
d. Relevant technologies & libraries:
• Python 3.x, interactions.py (Discord API wrapper)
• ddddocr (ONNX based OCR)
• JSON file handling (built-in)
• Standard Python modules (asyncio, json, os)