chsami§microbot

Imported from gencau/test-practices-agent-configurations (dataset/repos/chsami§microbot/AGENTS.md). Install upstream with npx skills add gencau/test-practices-agent-configurations --skill chsami§microbot. Copyright stays with the author.

Microbot Project Notes (for Codex)

Microbot at a Glance

Microbot is a RuneLite-based Old School RuneScape client fork with an always-on hidden plugin that hosts automation scripts. It packages a shaded client for end users and keeps developer ergonomics via Queryable caches and script helpers under microbot/util. The build mirrors upstream RuneLite as a composite Gradle setup.

Tech Stack

• Java target 11 (develop/run with JDK 17+), Gradle wrapper, composite builds (cache, runelite-api, runelite-client, runelite-gradle-plugin, runelite-jshell).
• RuneLite client + plugin APIs, LWJGL, Guice, Lombok, OkHttp, Gson, Logback/SLF4J.
• CI helper ci/build.sh bootstraps glslang then runs ./gradlew :buildAll.

Repo Map

• runelite-client/ – Main client (:client) containing the Microbot plugin and shaded jar assembly.
• runelite-api/ – RuneLite API included build consumed by the client.
• runelite-gradle-plugin/ – Gradle plugins for assemble/index/jarsign tasks.
• runelite-jshell/ – JShell support artifacts.
• cache/ – Cache tools/build used by RuneLite.
• docs/ – User/dev docs and static site assets.
• config/ – Shared Checkstyle configuration.
• ci/ – CI build helper script.

How to Validate Changes

• Fast sanity: ./gradlew :client:compileJava
• Full build (all included builds): ./gradlew buildAll
• Assemble shaded client: ./gradlew :client:assemble (creates runelite-client/build/libs/*-shaded.jar and microbot-<version>.jar)
• Tests are disabled by default via Gradle config; enable/selectively run if you add tests (./gradlew :client:runTests or runDebugTests).

Non-Negotiable Rules

• Never instantiate caches or queryables directly; always use Microbot.getRs2XxxCache().query() or .getStream() (see runelite-client/src/main/java/net/runelite/client/plugins/microbot/api/QUERYABLE_API.md).
• Do not block or sleep on the RuneLite client thread; long work belongs on script/executor threads.
• Keep logging minimal; avoid PII/session identifiers and respect existing log levels/patterns.
• Preserve the hidden/always-on nature of MicrobotPlugin and its config panel wiring.
• Follow Checkstyle/Lombok patterns already in the codebase; do not downgrade security (e.g., telemetry token handling, HTTP clients) without discussion.

Review Guidelines

• P0: Anything that can crash the client, block the client thread, break world hopping/login, corrupt cache/queryable invariants, or expose credentials/telemetry tokens.
• P1: Regressions to script loop timing, overlay correctness, plugin discovery/config panels, packaging (shaded jar/version props), or build reproducibility.
• Check threading (client vs script), cache access patterns, Gradle task wiring, and error handling around network calls.

When Unsure

• Start with docs/ARCHITECTURE.md and docs/decisions/ for background.
• API and script usage: runelite-client/src/main/java/net/runelite/client/plugins/microbot/api/README.md and QUERYABLE_API.md.
• Development/setup: docs/development.md; installation: docs/installation.md.
• Still unclear? Ask in Discord (link in README.md) or leave TODO with assumption noted.