How yolkorg/yolkbot works
Project Type and Purpose
• Yolkbot is an open-source library and CLI/browser toolset for building Shell Shockers bots in minimal code.
• It provides:
• A core JavaScript/TypeScript library (under /src) that handles networking, game‐state decoding, dispatching actions, pathfinding, and WASM integration.
• A CLI tool (/cli) for scraping game data, building releases, and publishing to npm.
• A browser build target (/browser) that packages the core library for front-end use.
• The README emphasizes ease of bot creation, automated data scraping, and multi-target packaging.
File Structure
• Top-level:
• /src – Core library modules.
• /cli – Scripts for scraping, building, and publishing.
• /browser – Build and entry points for a browser-compatible bundle.
• /alpha and /prod – Likely environment configurations or prebuilt assets.
• CI config under .github/workflows/scrape.yml to automate data scraping.
• Within /src:
• socket.js, matchmaker.js, comm/CommIn.js & CommOut.js – Network layer.
• dispatches/ – Action handlers (Fire, Move, Chat, etc.).
• constants/ – Game data (maps, items, sounds) populated by the scraper.
• pathing/ – A* pathfinding utilities.
• wasm/ – A WASM loader and helpers for performance-critical code.
• /cli/scrape subdivides into fromJS, fromJSON, fromWS—each collecting different data sources.
Extract Architecture Insights from README
• Emphasis on “unified way” and “archive of game data” hints at a layered architecture:
• Data ingestion and update via CLI scraper
• Core library with clear API for bot authors
• Packaging layers for different environments (Node CLI vs Browser)
Main Components and Their Interactions
a. Core Library (Node & Browser)
– Modules: API (api.js), Bot (bot.js), Network (socket, comm), Dispatchers, Pathing, WASM, Constants
– Exposes a simple interface: instantiate a Bot, register event handlers, connect to game.
b. CLI Tool
– Scrape submodule gathers game data (JS files, JSON endpoints, WebSocket feeds).
– Build and publish modules compile and bundle /src into npm packages.
– Invoked manually or via CI.
c. Browser Bundle
– Uses browser/compile.js to produce global and module-format JS bundles.
– Hosts the same core library in client environments.
d. Data Sources
– Shell Shockers servers and web assets (for realtime game data).
– JSON APIs and scraped JS files.
e. External Services
– GitHub Actions (automate scraping and builds).
– npm registry (publishing).
f. Consumers
– Bot developers writing custom scripts against the Yolkbot API.
– CI pipelines keeping constants up to date.
Architectural Patterns & Principles
• Layered Architecture:
• Data Layer (constants, scraper)
• Core Logic Layer (network, dispatch, pathfinding, WASM)
• API Layer (Bot class, user hooks)
• Presentation/Packaging Layer (CLI, Browser)
• Plugin-style dispatch handlers: each game action lives in its own module.
• CI/CD integration for automated data updates.
• Dual-target bundling (Node & browser) via separate entry points.