Sailing base by chsami · Pull Request #1614 · chsami/Microbot

chsami · 2025-11-23T16:13:05Z

Microbot – Sailing utilities are live (API preview)

Sailing support in Microbot just got a serious upgrade. We now have a dedicated Rs2Sailing utility that centralises most low-level sailing actions, so scripts can focus on logic instead of boilerplate.

What’s included

Basic boat state and control

isOnBoat() – Detects if the player is currently on a player boat.
isNavigating() – Checks if the player is at the helm.
boardBoat() – Uses gangplanks/moorings to board any nearby sailing vessel.
disembarkBoat() – Temporary but robust disembark logic that scans tiles for valid gangplanks/moorings and clicks “Disembark”.
navigate() – Moves the player to the steering wheel/helm and enters navigation mode.

Boat movement and sail control

Movement state helpers:
- isMovingForward()
- isMovingBackward()
- isStandingStill()
Sail control:
- setSails() – Sets sails to move forward (via the Sailing sidepanel controls).
- unsetSails() – Brings the boat to a stop.
clickSailButton() – Low-level helper to press the set-sail button in the sidepanel.

Heading and pathing towards a target

getPlayerBoatLocation() – Resolves the player’s world position relative to the boat, handling instances vs main world projection.
getDirection(WorldPoint target) – Computes the 16-direction index towards a target world point.
setHeading(Heading heading) – Issues a Set-Heading menu action with the correct world view ID.
sailTo(WorldPoint target) – High-level helper that:
- Boards the boat if needed.
- Takes the helm.
- Computes the correct heading towards the target.
- Sets the heading.
- Ensures the boat is moving forward.

Automatic sail trimming on gusts of wind

handleChatMessage(ChatMessage event) – Listens to game messages.
- When “You feel a gust of wind” appears, it triggers trimSails() on a separate client thread.
trimSails() – Searches for all known sail object IDs (various sizes/woods + colossal sails) and interacts with “Trim”, waiting for XP gain as confirmation.

This gives scripts:

Automatic reaction to wind gusts.
Centralised trim logic for all supported sails.

Cargo interaction

openCargo() – Supports all raft/2x5/large cargo hold variants (all wood types and open/closed IDs) and opens the cargo hold if you are on a boat.

Boat type abstraction (work in progress)

getBoatType() – Resolves the boat type based on VarPlayerID.SAILING_SIDEPANEL_BOAT_TYPE.
getSteeringForBoatType() – Returns the correct steering object ID per boat type.
- Currently wired for RAFT, hooks for SKIFF and SLOOP are ready but not filled in yet.

Port task integration

getPortTasksVarbits() – Returns all active port task varbits as a Map<PortTaskVarbits, Integer> (only those with value > 0 and type ID).
getPortTaskData(int varbitValue) – Maps a varbit value to PortTaskData so scripts can reason about which tasks are active.

How to use this in scripts

Examples of what you can do with this API right now:

Sail to specific world points with Rs2Sailing.sailTo(targetWorldPoint).
Make scripts that automatically trim sails when wind gusts occur, using handleChatMessage in your plugin.
Open and manage cargo holds in a generic way across all boat sizes and wood types.
Inspect and react to active port tasks via getPortTasksVarbits() and getPortTaskData(...).

Notes / caveats

Disembark handling is explicitly marked as a temporary solution; it will be replaced once the new sailing API is finalised.
Boat type handling is structured but only fully implemented for RAFT for now.
ignoreBoatWorldView and more advanced world-view logic are available for future expansions and edge cases.

If you are writing sailing-related scripts, you should stop reinventing the wheel and rely on Rs2Sailing for:

Boarding/disembarking
Navigation mode
Heading control
Sail control
Cargo interaction
Port task lookups

Feedback and edge cases (especially odd ports, instances, or disembark failures) are welcome so we can harden this API.

coderabbitai · 2025-11-23T16:13:22Z

Important

Review skipped

Auto incremental reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Walkthrough

This pull request implements a comprehensive sailing system for the microbot plugin. The changes include updating the microbot version in the build configuration, modifying core utility classes to support client-thread execution for safer data access, integrating a new Rs2Sailing utility class with extensive boat navigation and control capabilities, introducing multiple sailing-related data classes (BoatType, Heading, PortLocation, PortPaths, etc.), creating a SailingPanel UI component for route selection and navigation, and refactoring existing utilities like Rs2GameObject and NewMenuEntry to handle world view context. Additionally, the example plugin is updated to demonstrate overlay management using the new infrastructure.

Possibly related PRs

Game objects new simplified api #1606: Modifies Rs2GameObject, ExamplePlugin/Script, and client-thread invocation patterns with overlapping changes to how game objects are fetched and interacted with.
2.0.9 #1530: Updates Microbot.java to route cache and varbit access through the client thread, implementing similar patterns for thread-safe data retrieval.
fix: update varbit and varplayer checks to use correct Microbot methods #1532: Updates call sites to use Microbot accessors for varbit and varplayer access instead of direct client calls, complementing the accessor modifications in this PR.

Pre-merge checks and finishing touches

❌ Failed checks (1 warning, 1 inconclusive)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 13.45% which is insufficient. The required threshold is 80.00%.	You can run `@coderabbitai generate docstrings` to improve docstring coverage.
Title check	❓ Inconclusive	The title "Sailing base" is vague and does not clearly describe the main change; it lacks specificity about what sailing functionality is being added.	Consider a more descriptive title such as "Add Rs2Sailing utility for centralized sailing actions" to better communicate the PR's primary contribution.

✅ Passed checks (1 passed)

Check name	Status	Explanation
Description check	✅ Passed	The description is comprehensive and directly related to the changeset, providing clear examples of the new Rs2Sailing API, usage patterns, and implementation details.

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

coderabbitai

Actionable comments posted: 3

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (2)

runelite-client/src/main/java/net/runelite/client/plugins/microbot/util/gameobject/Rs2GameObject.java (2)
1523-1607: Boat-aware scene traversal has inconsistent plane handling and ignores predicates

Two problems in getSceneObjects(...):

Plane/scene selection logic is self-contradictory

In the else branch you call player.getWorldView().getScene() even though worldView is known to be null, which can NPE if that path is ever taken.

int z = Rs2Sailing.isOnBoat() ? 3 : player.getWorldView().getPlane(); is then used as an upper bound in for (int h = 0; h < z; h++), but z is a plane index, not a plane count. This means:

When plane == 0, you never iterate any tiles.

When plane == 1, you only scan tiles[0].

On boats, if the relevant tiles are not all on planes < 3, they may be skipped.

This will cause object enumeration to silently miss the actual plane in several configurations.

Boat branch of getSceneObjects(extractor, predicate, anchorLocal, distance) ignores the predicate

When Rs2Sailing.isOnBoat() is true, you return getSceneObjects(extractor).collect(...) without applying predicate or distance.

Callers like getGameObject(id, ...) rely on this predicate to limit results to a specific id/name, so on a boat they may receive the first arbitrary object in the scene instead of a matching one.

Consider reworking these pieces along the following lines:

Use worldView consistently with a safe fallback:
WorldView worldView = player.getWorldView();
WorldView fallback = Microbot.getClient().getTopLevelWorldView();
WorldView effective = worldView != null ? worldView : fallback;
Scene scene = effective.getScene();
Tile[][][] tiles = scene.getTiles();
int z = effective.getPlane(); // or a known constant if you truly need a fixed boat plane
Iterate the plane you actually want (e.g. Tile tile = tiles[z][x][y];) or, if you intend to scan all planes, use a fixed bound (for (int h = 0; h < Constants.MAX_Z; h++)), not a single plane index.

In getSceneObjects(extractor, predicate, anchorLocal, distance), keep the boat-specific distance relaxation but still honor the predicate:
if (Rs2Sailing.isOnBoat()) {
    return getSceneObjects(extractor)
        .filter(predicate)
        .collect(Collectors.toList());
}
1738-1741: fetchGameObjects(..., WorldPoint) incorrectly delegates to fetchTileObjects

The overload:
private static <T extends TileObject> List<T> fetchGameObjects(Predicate<? super T> predicate, WorldPoint anchor) {
    return fetchTileObjects(predicate, anchor, Constants.SCENE_SIZE);
}
never actually fetches GameObjects; it calls fetchTileObjects, so any use of this method will silently return tile/ground/wall objects instead of game objects.

It should delegate to the fetchGameObjects(predicate, anchor, distance) overload:
 private static <T extends TileObject> List<T> fetchGameObjects(Predicate<? super T> predicate, WorldPoint anchor) {
-    return fetchTileObjects(predicate, anchor, Constants.SCENE_SIZE);
+    return fetchGameObjects(predicate, anchor, Constants.SCENE_SIZE);
 }

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between fc3bd32 and 4c0f384.

⛔ Files ignored due to path filters (1)

runelite-client/src/main/resources/net/runelite/client/plugins/microbot/shortestpath/sailing_icon.png is excluded by !**/*.png

📒 Files selected for processing (20)

runelite-client/pom.xml (1 hunks)
runelite-client/src/main/java/net/runelite/client/plugins/microbot/Microbot.java (2 hunks)
runelite-client/src/main/java/net/runelite/client/plugins/microbot/MicrobotPlugin.java (3 hunks)
runelite-client/src/main/java/net/runelite/client/plugins/microbot/example/ExamplePlugin.java (2 hunks)
runelite-client/src/main/java/net/runelite/client/plugins/microbot/example/ExampleScript.java (2 hunks)
runelite-client/src/main/java/net/runelite/client/plugins/microbot/example/ExampleScriptOverlay.java (1 hunks)
runelite-client/src/main/java/net/runelite/client/plugins/microbot/shortestpath/SailingPanel.java (1 hunks)
runelite-client/src/main/java/net/runelite/client/plugins/microbot/shortestpath/ShortestPathPlugin.java (3 hunks)
runelite-client/src/main/java/net/runelite/client/plugins/microbot/util/gameobject/Rs2GameObject.java (13 hunks)
runelite-client/src/main/java/net/runelite/client/plugins/microbot/util/menu/NewMenuEntry.java (4 hunks)
runelite-client/src/main/java/net/runelite/client/plugins/microbot/util/player/Rs2Player.java (2 hunks)
runelite-client/src/main/java/net/runelite/client/plugins/microbot/util/sailing/Rs2Sailing.java (1 hunks)
runelite-client/src/main/java/net/runelite/client/plugins/microbot/util/sailing/data/BoatPathFollower.java (1 hunks)
runelite-client/src/main/java/net/runelite/client/plugins/microbot/util/sailing/data/BoatType.java (1 hunks)
runelite-client/src/main/java/net/runelite/client/plugins/microbot/util/sailing/data/Heading.java (1 hunks)
runelite-client/src/main/java/net/runelite/client/plugins/microbot/util/sailing/data/LedgerID.java (1 hunks)
runelite-client/src/main/java/net/runelite/client/plugins/microbot/util/sailing/data/PortLocation.java (1 hunks)
runelite-client/src/main/java/net/runelite/client/plugins/microbot/util/sailing/data/PortPaths.java (1 hunks)
runelite-client/src/main/java/net/runelite/client/plugins/microbot/util/sailing/data/PortTaskVarbits.java (1 hunks)
runelite-client/src/main/java/net/runelite/client/plugins/microbot/util/sailing/data/RelativeMove.java (1 hunks)

🧰 Additional context used

📓 Path-based instructions (7)

runelite-client/src/main/java/net/runelite/client/plugins/microbot/**/*.java

📄 CodeRabbit inference engine (AGENTS.md)

runelite-client/src/main/java/net/runelite/client/plugins/microbot/**/*.java: Place all gameplay automation code under runelite-client/src/main/java/net/runelite/client/plugins/microbot
Prefix configuration interfaces with the plugin name (e.g., ExampleConfig) within microbot plugins

Files:

runelite-client/src/main/java/net/runelite/client/plugins/microbot/util/sailing/data/RelativeMove.java
runelite-client/src/main/java/net/runelite/client/plugins/microbot/util/sailing/data/BoatType.java
runelite-client/src/main/java/net/runelite/client/plugins/microbot/example/ExampleScriptOverlay.java
runelite-client/src/main/java/net/runelite/client/plugins/microbot/shortestpath/SailingPanel.java
runelite-client/src/main/java/net/runelite/client/plugins/microbot/util/player/Rs2Player.java
runelite-client/src/main/java/net/runelite/client/plugins/microbot/MicrobotPlugin.java
runelite-client/src/main/java/net/runelite/client/plugins/microbot/util/sailing/data/PortTaskVarbits.java
runelite-client/src/main/java/net/runelite/client/plugins/microbot/util/sailing/data/PortPaths.java
runelite-client/src/main/java/net/runelite/client/plugins/microbot/util/sailing/data/LedgerID.java
runelite-client/src/main/java/net/runelite/client/plugins/microbot/util/sailing/data/PortLocation.java
runelite-client/src/main/java/net/runelite/client/plugins/microbot/util/sailing/Rs2Sailing.java
runelite-client/src/main/java/net/runelite/client/plugins/microbot/util/sailing/data/BoatPathFollower.java
runelite-client/src/main/java/net/runelite/client/plugins/microbot/example/ExamplePlugin.java
runelite-client/src/main/java/net/runelite/client/plugins/microbot/example/ExampleScript.java
runelite-client/src/main/java/net/runelite/client/plugins/microbot/util/sailing/data/Heading.java
runelite-client/src/main/java/net/runelite/client/plugins/microbot/shortestpath/ShortestPathPlugin.java
runelite-client/src/main/java/net/runelite/client/plugins/microbot/Microbot.java
runelite-client/src/main/java/net/runelite/client/plugins/microbot/util/gameobject/Rs2GameObject.java
runelite-client/src/main/java/net/runelite/client/plugins/microbot/util/menu/NewMenuEntry.java

runelite-client/src/main/java/net/runelite/client/plugins/microbot/util/**/*.java

📄 CodeRabbit inference engine (AGENTS.md)

Put shared helpers under .../microbot/util

Files:

runelite-client/src/main/java/net/runelite/client/plugins/microbot/util/sailing/data/RelativeMove.java
runelite-client/src/main/java/net/runelite/client/plugins/microbot/util/sailing/data/BoatType.java
runelite-client/src/main/java/net/runelite/client/plugins/microbot/util/player/Rs2Player.java
runelite-client/src/main/java/net/runelite/client/plugins/microbot/util/sailing/data/PortTaskVarbits.java
runelite-client/src/main/java/net/runelite/client/plugins/microbot/util/sailing/data/PortPaths.java
runelite-client/src/main/java/net/runelite/client/plugins/microbot/util/sailing/data/LedgerID.java
runelite-client/src/main/java/net/runelite/client/plugins/microbot/util/sailing/data/PortLocation.java
runelite-client/src/main/java/net/runelite/client/plugins/microbot/util/sailing/Rs2Sailing.java
runelite-client/src/main/java/net/runelite/client/plugins/microbot/util/sailing/data/BoatPathFollower.java
runelite-client/src/main/java/net/runelite/client/plugins/microbot/util/sailing/data/Heading.java
runelite-client/src/main/java/net/runelite/client/plugins/microbot/util/gameobject/Rs2GameObject.java
runelite-client/src/main/java/net/runelite/client/plugins/microbot/util/menu/NewMenuEntry.java

**/*.java

📄 CodeRabbit inference engine (AGENTS.md)

**/*.java: Use tabs for indentation, follow the brace placement style exemplified in MicrobotPlugin.java, and keep lines under 120 characters
Use UpperCamelCase for types and lowerCamelCase for members

Files:

runelite-client/src/main/java/net/runelite/client/plugins/microbot/util/sailing/data/RelativeMove.java
runelite-client/src/main/java/net/runelite/client/plugins/microbot/util/sailing/data/BoatType.java
runelite-client/src/main/java/net/runelite/client/plugins/microbot/example/ExampleScriptOverlay.java
runelite-client/src/main/java/net/runelite/client/plugins/microbot/shortestpath/SailingPanel.java
runelite-client/src/main/java/net/runelite/client/plugins/microbot/util/player/Rs2Player.java
runelite-client/src/main/java/net/runelite/client/plugins/microbot/MicrobotPlugin.java
runelite-client/src/main/java/net/runelite/client/plugins/microbot/util/sailing/data/PortTaskVarbits.java
runelite-client/src/main/java/net/runelite/client/plugins/microbot/util/sailing/data/PortPaths.java
runelite-client/src/main/java/net/runelite/client/plugins/microbot/util/sailing/data/LedgerID.java
runelite-client/src/main/java/net/runelite/client/plugins/microbot/util/sailing/data/PortLocation.java
runelite-client/src/main/java/net/runelite/client/plugins/microbot/util/sailing/Rs2Sailing.java
runelite-client/src/main/java/net/runelite/client/plugins/microbot/util/sailing/data/BoatPathFollower.java
runelite-client/src/main/java/net/runelite/client/plugins/microbot/example/ExamplePlugin.java
runelite-client/src/main/java/net/runelite/client/plugins/microbot/example/ExampleScript.java
runelite-client/src/main/java/net/runelite/client/plugins/microbot/util/sailing/data/Heading.java
runelite-client/src/main/java/net/runelite/client/plugins/microbot/shortestpath/ShortestPathPlugin.java
runelite-client/src/main/java/net/runelite/client/plugins/microbot/Microbot.java
runelite-client/src/main/java/net/runelite/client/plugins/microbot/util/gameobject/Rs2GameObject.java
runelite-client/src/main/java/net/runelite/client/plugins/microbot/util/menu/NewMenuEntry.java

**/pom.xml

📄 CodeRabbit inference engine (AGENTS.md)

Target Java 11 via maven-compiler-plugin using 11 in all module POMs

Files:

runelite-client/pom.xml

runelite-client/src/main/java/net/runelite/client/plugins/microbot/example/**/*.java

📄 CodeRabbit inference engine (AGENTS.md)

Keep runnable examples under .../microbot/example

Files:

runelite-client/src/main/java/net/runelite/client/plugins/microbot/example/ExampleScriptOverlay.java
runelite-client/src/main/java/net/runelite/client/plugins/microbot/example/ExamplePlugin.java
runelite-client/src/main/java/net/runelite/client/plugins/microbot/example/ExampleScript.java

runelite-client/src/main/java/net/runelite/client/plugins/microbot/@(!(util|example))/**/*.java

📄 CodeRabbit inference engine (AGENTS.md)

For new automation scripts, reuse the scheduler pattern demonstrated in ExampleScript

Files:

runelite-client/src/main/java/net/runelite/client/plugins/microbot/shortestpath/SailingPanel.java
runelite-client/src/main/java/net/runelite/client/plugins/microbot/shortestpath/ShortestPathPlugin.java

runelite-client/src/main/java/net/runelite/client/plugins/microbot/MicrobotPlugin.java

📄 CodeRabbit inference engine (AGENTS.md)

When adding panel controls or overlays, update the Microbot navigation panel setup in MicrobotPlugin and provide default config values

Files:

runelite-client/src/main/java/net/runelite/client/plugins/microbot/MicrobotPlugin.java

🧠 Learnings (12)

📓 Common learnings

Learnt from: CR
Repo: chsami/Microbot PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-10-16T17:14:29.778Z
Learning: Applies to runelite-client/src/main/java/net/runelite/client/plugins/microbot/MicrobotPlugin.java : When adding panel controls or overlays, update the Microbot navigation panel setup in MicrobotPlugin and provide default config values