[Getting started] Scripting for OSBot Native

With the release of OSBot Native, which focuses on native code, getting started with scripting may seem a bit daunting at first. However, once you get the hang of it, scripting is just as easy as it ever was!

OSBot Native is built on the Rust language, which means we mainly support scripting in Rust natively. Other FFI-compatibles languages will be added later on, but there is no ETA for this yet.

Getting Started

To set up a new script project, use the following command:

cargo new sample_script --lib

This command will create a new project, including a `lib.rs` and `Cargo.toml` file. The `lib.rs` file will serve as your entry point for the script. You can add other files if needed, but make sure to keep `lib.rs` as the main file.

Next, you’ll want to add the OSBot API dependency and set up your crate as a `cdylib` (this tells Rust that we want to build a shared library).

Open the `Cargo.toml` file and ensure it looks something like this:

[package] 
name = "sample_script"
version = "0.1.0"
edition = "2021"

[lib]
crate-type = ["cdylib"]

[dependencies]
osbot_api = { git = "https://github.com/OSBotNative/stub_api", features = ["script"] }

Depending on your IDE, it should automatically start syncing and downloading the dependencies. If this doesn't happen, you can manually run the following command:

cargo update

Now, open the `lib.rs` file, delete any existing content, and paste in the script template.

use osbot_api::api::script::script::Script;
use osbot_api::api::script::script_metadata::{ScriptCategory, ScriptMetadata};

#[no_mangle]
pub extern "C" fn metadata() -> ScriptMetadata {
  ScriptMetadata {
    name: "Sample Script".to_string(),
    author: "Patrick".to_string(),
    version: 1.0,
    info: "Getting started with native scripting".to_string(),
    logo: "https://i.gyazo.com/cff84f44847c548c9024b5a06384a73d.png".to_string(),
    category: ScriptCategory::Other,}}

#[osbot_api::script_exports]
pub struct SampleScript;
impl Script for SampleScript {
  fn new() -> Self {
    Self { }}
  
  fn on_start(&mut self, params: Option<String>) {}
  
  fn on_loop(&mut self) -> i32 {
    250}}

Much of this code should be familiar to you, though in a new style. We’ve done our best to make the entire API feel as close to the Java API as possible, making the transition to Rust as easy as it can be!
As in Java, a script will include the standard functions like `on_start`, `on_loop`, `on_pause`, `on_stop`, `on_resume`, and `on_render`. You can Ctrl+Click on `Script` (between `impl` and `for`) to open the `Script` trait file and see all the available functions.

Let’s start by creating a simple powerfisher script. The pseudocode for this would look something like:

if inventory is full {
  drop all fish
} else {
  if not fishing {
    start fishing
  }
}

All API functions are prefixed with the object you want to interact with, followed by the action: `inventory_something`, `bank_something`, `quests_something`, `npcs_something`, etc. So to check if the inventory is full, you can use:

if inventory_is_full() { }

If the inventory is full, we want to drop the fish. This is just as easy:

inventory_drop_all_by_id(317);
OR
inventory_drop_all_by_name("Shrimp");

These API functions automatically handle opening the inventory if it isn’t already open.

And just like that, half of our script is complete!

Interacting with the fishing spot is a bit more complex, but still quite easy. First, we need to get the local player and check if it exists. If it does, we check whether the player is moving or animating. If neither is true, we can start looking for a fishing spot. If one is found, we can interact with it.

In Java, we'd use `!= null` to check if something exists. Rust doesn’t have this, so we use the `Option` type. An `Option` can be either `Some` or `None`, similar to checking for `null` in Java. For scripting, I prefer the following syntax:

if let Some(local_player) = players_get_local_player() { }

This attempts to get the local player, and if successful (`Some`), it returns the value. In Java, this would be written like:

Player localPlayer = getPlayers().myPlayer();if (localPlayer != null) { }

To check if the local player is idle (not moving or animating), we can do the following:

if !local_player.is_moving() && !local_player.is_animating() { }

Once the player is idle, we can find and interact with the fishing spot and wait until we're fishing. For this example, we'll wait up till 7500 milliseconds and checking if we're fishing every 250 milliseconds. This is done as follows:

if let Some(fishing_spot) = npcs_find_closest_by_name("Fishing spot") {
  if fishing_spot.interact("Net") {
    utils_sleep_conditional(7500, 250, || { local_player.is_animating() });}}

Just like item dropping handles the required conditions to drop the items, interact will ensure you can interact with the fishing spot by either walking to it or moving the camera. If you want to tweak these settings, check out the function `interact_args`.

And now you have your first script completed! On to building and running it.

Building The Script

Read Section 14:
https://osbot.org/forum/topic/203264-getting-started-rust-project-setup-rustrover-ide/

I hope this post gives enough information to start scripting using the Native API. If there are any questions; ask away!

- The OSBot Team