Skip to content

script tut #128

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
AndNowWhat wants to merge 2 commits into
base: master
Choose a base branch
from
Open

script tut #128

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
2ed39bb
script tut
AndNowWhat May 7, 2026
d04c772
Update 09-publishing-to-sdn.md
AndNowWhat May 7, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 21 additions & 7 deletions docs/Guides/ScriptSubmissionWorkflow.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,18 @@
# Script Submission Workflow
---
title: Script Submission Workflow
description: How to submit changes to your scripts using feature branches and squashed commits — GitHub Desktop and Git CLI walkthroughs.
---

import React from 'react';
import ContentBlock from '@site/src/components/ContentBlock';

<ContentBlock title="Overview">

This document outlines the process for submitting changes to your scripts using feature branches and squashing commits. This ensures that your script reviewers can review all changes in a single, consolidated commit, improving the review process.

## Step-by-Step Workflow using Github Desktop (Recommended)
</ContentBlock>

<ContentBlock title="Step-by-Step Workflow using Github Desktop (Recommended)">

### Clone the Repository
1. Open **GitHub Desktop**.
Expand Down Expand Up @@ -64,9 +74,9 @@ Following this workflow helps ensure that your reviewers can see all your change

If you have any questions or run into any issues, please reach out!

---
</ContentBlock>

## Step-by-Step Workflow using Git CLI
<ContentBlock title="Step-by-Step Workflow using Git CLI">

### Clone the Repository
If you haven't already cloned your repository, you can do so using the following command:
Expand Down Expand Up @@ -153,9 +163,9 @@ git branch -d feature/your-feature-name
git push origin --delete feature/your-feature-name
```

---
</ContentBlock>

## Summary of Commands
<ContentBlock title="Summary of Commands">

1. Create and switch to a new branch:
```bash
Expand Down Expand Up @@ -192,8 +202,12 @@ git push origin --delete feature/your-feature-name
git push origin --delete feature/your-feature-name
```

---
</ContentBlock>

<ContentBlock title="Wrap-up">

Following this workflow helps ensure that your reviewers can see all your changes in a single commit, making the review process smoother and more efficient.

If you have any questions or run into any issues, please reach out!

</ContentBlock>
73 changes: 73 additions & 0 deletions docs/Guides/Tutorial/01-install.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,73 @@
---
title: 1. Install & First Launch
description: Buy a subscription on the BotWithUs website, install the loader, and exclude it from antivirus.
sidebar_position: 1
---

import ContentBlock from '@site/src/components/ContentBlock';
import BrowserWindow from '@site/src/components/BrowserWindow';

<ContentBlock title="Buy a subscription">
<BrowserWindow url="https://botwithus.com">

BotWithUs is paid software. Before anything else, you need an active subscription.

1. Create an account on [botwithus.com](https://botwithus.com) and sign in.
2. Choose how you want to pay — wallet top-up or direct card checkout.

**Option 1 — Top up your wallet, then subscribe**

Useful if you want to pay with crypto, or keep a balance for renewals.

- Open [**My Account**](https://botwithus.com/profile/) and under **Wallet Balance** click **Manage** (or go straight to your [**Wallet**](https://botwithus.com/wallet/)).
- Click **Add Funds** and top up with card or crypto.

> ![Add funds to your wallet](../images/TOP_UP.png)

- Head to [**Plans**](https://botwithus.com/plans/), pick your subscription, and pay with your wallet balance.

> ![Choose a subscription plan](../images/CHOOSE_SUB_PLAN.png)

**Option 2 — Pay directly with card**

- Go straight to [**Plans**](https://botwithus.com/plans/) and pay with a card at checkout.

Once your subscription is active you can review or change it any time from [**Manage Subscription**](https://botwithus.com/subscription/manage/).

:::info Payment issues?
If a payment went through but your subscription isn't showing as active, ping a `@Dev` in the [BotWithUs Discord](https://discord.gg/botwithus) and they'll sort it out.
:::

</BrowserWindow>
</ContentBlock>

<ContentBlock title="Install the loader">

1. Head to the [**Download**](https://botwithus.com/download) page and grab the loader. The quick guide on the same page tells you which build to pick.
2. Run the installer. Defaults are fine — it puts the loader in your `BotWithUs/` user folder.
3. The first launch creates `~/BotWithUs/scripts/local/` (where your own scripts go later) and `~/BotWithUs/scripts/sdn/` (where marketplace scripts get cached).

</ContentBlock>

<ContentBlock title="Exclude the loader from antivirus">

The loader injects into the RuneScape client process, which is exactly the kind of behaviour antivirus tools like to flag. Most users hit at least one false positive.

Add an exclusion for the BotWithUs install folder *before* you run the loader for the first time. Even Microsoft Defender will quietly quarantine the executable on some systems.

- **Windows Defender:** Settings → Privacy & security → Windows Security → Virus & threat protection → Manage settings → Add or remove exclusions → Add an exclusion → Folder → pick your `BotWithUs` install folder.
- **Third-party AVs (Avast, Bitdefender, Kaspersky, Malwarebytes, etc.):** add the same folder to the AV's allow/exclusions list. The exact menu varies, but every AV has one.

If the loader vanishes a few seconds after you launch it, or never produces a window at all, antivirus is the first thing to check. The loader is signed and clean — it's the injection that triggers heuristics.

</ContentBlock>

<ContentBlock title="First launch — sign in">

1. Start the loader.
2. Sign in with the same account you used on [botwithus.com](https://botwithus.com). The loader fetches your active subscription from the website automatically — there's no separate serial or activation key.
3. Once you're signed in, the toolbar lights up and you're ready to add a game account.

</ContentBlock>

**Next:** [launching accounts →](./02-launching-accounts.md)
64 changes: 64 additions & 0 deletions docs/Guides/Tutorial/02-launching-accounts.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,64 @@
---
title: 2. Launching Accounts
description: Launch classic and launcher accounts through the BotWithUs loader, plus session limits.
sidebar_position: 2
---

import ContentBlock from '@site/src/components/ContentBlock';

<ContentBlock title="Two account types">

RuneScape has two login systems. **Both run directly from the BotWithUs loader** — the only difference is how the loader gets hold of your accounts.

| Account type | How you log in normally | What you'll do here |
|---|---|---|
| **Classic** | Username + password directly into the game | Save credentials in the **account manager**, then create a session |
| **Launcher** | The launcher → click an account tile | Have the **launcher open** so the loader can pull your accounts in, then create a session |

If you're not sure which you have: if you log in through the **launcher**, it's a launcher account.

</ContentBlock>

<ContentBlock title="Launching a classic account">

This is the simpler path.

1. In the loader, open the **Account Manager** (button on the toolbar).
2. Click **Add account** and enter your username and password.
- You can leave credentials blank, but **autologin won't work** if you do.

> ![Adding an account in the loader](../images/ADD_ACCOUNT_LOADER.png)

3. Save the entry.
4. Back on the main loader screen, click **Launch account** then select classic or launcher.
5. Choose your saved account from the list.
6. Click **Launch session**.

A game client window opens. After about **5 seconds**, BotWithUs injects into it. You'll know injection succeeded when the **BotWithUs logo** appears in the corner of the client — this is a prerequisite for opening the bot menu in [chapter 3](./03-bot-menu.md).

> ![Loader injecting into the client](../images/LOADER_INJECT.png)

</ContentBlock>

<ContentBlock title="Launching a launcher account">

Launcher accounts can't store credentials inside the loader — the launcher handles that. The loader pulls your accounts straight from the launcher, so it just needs to be **open** in the background.

1. Open the **launcher** and sign in.
2. Switch to the **BotWithUs loader**.
3. Click **Add account**, and select the account type.
4. Click **Clear and repopulate** — the loader will re-read your accounts from the Jagex Launcher.
5. Click **Launch session**.

The loader starts the client and BWU injects. It may take up to 10 seconds for the loader overlay to show in-game.

</ContentBlock>

<ContentBlock title="Session limits">

- Your basic subscription allows for 2 sessions, any additional session can be purchased on the website if you want to bot more accounts at the same time.
- Closing the client frees a slot.

</ContentBlock>

**Next:** [the bot menu →](./03-bot-menu.md)
65 changes: 65 additions & 0 deletions docs/Guides/Tutorial/03-bot-menu.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,65 @@
---
title: 3. The Bot Menu
description: Open the BotWithUs in-game menu, learn the hotkeys, and tell Scripts apart from SDN Scripts.
sidebar_position: 3
---

import ContentBlock from '@site/src/components/ContentBlock';

<ContentBlock title="Opening the menu">

This chapter assumes you've already launched a client and BotWithUs has injected — see [chapter 2](./02-launching-accounts.md) if the BWU logo isn't showing in the corner yet.

Open the **bot menu** in two ways:

- Press **Insert** on your keyboard, **or**
- Click the **BotWithUs logo** in the corner of the client.

The overlay opens on top of the game. From there, click **Scripts** to bring up the scripts window.

> ![Open the overlay and click Scripts](../images/OPEN_OVERLAY_AND_SCRIPTS.png)

</ContentBlock>

<ContentBlock title="Scripts vs SDN Scripts">

Inside the scripts window you'll see two tabs. Switch to the **SDN** tab to see anything you've subscribed to from the marketplace.

> ![Switch to the SDN tab in the scripts window](../images/SWITCH_TO_SDN_SCRIPTS_SCRIPTS_WINDOW.png)

| Tab | Where the scripts come from | When you'd use it |
|---|---------------------------------------------------|---|
| **Scripts** | `.jar` files you put in your local scripts folder | Scripts you wrote, or custom ones a friend sent you |
| **SDN** | The BotWithUs marketplace, downloaded on request | Anything you've subscribed to on [botwithus.net/sdn](https://botwithus.net/sdn) |

You'll meet "Scripts" again in [chapter 5](./05-first-script.md) when you build your own.

</ContentBlock>

<ContentBlock title='"I subscribed but no scripts are showing up"'>

Two things to check:

1. **Did you actually subscribe on the website?** Browse [botwithus.net/sdn](https://botwithus.net/sdn), click a script, and confirm it.
2. **Hit Refresh in the SDN tab.** No need to restart the loader — just click **Refresh** in the SDN tab and your new subscriptions will load.

After that, the script should appear under the **SDN** tab in the scripts window. Press the load button to start the download (usually instant or only a few seconds).

</ContentBlock>

<ContentBlock title="Running a script">

Same flow for both tabs:

1. Click the script's name in the list.
2. Its options window appears (every script has its own — read what it asks for).
3. Click **Play** to start the script. Some scripts have their own play button inside the script's configuration UI — use whichever the script provides.
4. Watch your character act on screen, and watch the script console for any issues.

> ![Configuring a script's options](../images/SCRIPT_OPTIONS.png)

To stop a script, click **Stop** in its window (it replaces the Play button). Closing the script's configuration window with the configuration icon does **not** stop the script — only **Stop** does. The main overlay can be hidden the same way: press **Insert** or click the BWU logo.

</ContentBlock>

**Next:** if you only want to *use* scripts, you're done. To start writing your own, head to [setting up your coding environment →](./04-ide-setup.md).
113 changes: 113 additions & 0 deletions docs/Guides/Tutorial/04-ide-setup.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,113 @@
---
title: 4. Setting Up Your Coding Environment
description: Install IntelliJ IDEA, get JDK 20, and clone the BotWithUs skeleton script.
sidebar_position: 4
---

import ContentBlock from '@site/src/components/ContentBlock';
import BrowserWindow from '@site/src/components/BrowserWindow';

<ContentBlock title="What you're installing and why">

Before you can write a script, you need three things on your machine:

| Tool | What it is | Why you need it |
|---|---|------------------------------------------------------------------------------------------------------------|
| **IntelliJ IDEA** | The code editor (an "IDE") | This is where you type, run, and build your scripts. This guide focuses on IntelliJ but any IDE will work. |
| **JDK 20** | The Java compiler | Scripts are written in Java; the JDK turns your code into a `.jar` BotWithUs can load |
| **Skeleton repo** | A pre-made starter project | Has all the BotWithUs APIs wired up so you can hit "build" and get a working script on day one |

</ContentBlock>

<ContentBlock title="Step 1 — Install IntelliJ IDEA Community">
<BrowserWindow url="https://www.jetbrains.com/idea/download/">

IntelliJ comes in two editions: **Community** (free) and **Ultimate** (paid). Community is just fine for everything we'll do.

1. Go to [jetbrains.com/idea/download](https://www.jetbrains.com/idea/download/).
2. Scroll down to the **Community Edition** section. Don't grab Ultimate by mistake — it's at the top of the page.
3. Click **Download**, run the installer.
4. Accept the defaults. The only useful checkbox is **Add "Open Folder as Project"** (it puts a right-click shortcut in Windows Explorer).
5. Launch IntelliJ when it finishes.

On first launch IntelliJ asks about themes and plugins — pick whatever you like, defaults are safe.

</BrowserWindow>
</ContentBlock>

<ContentBlock title="Step 2 — Clone the skeleton script">
<BrowserWindow url="https://github.com/BotWithUs/BwuScriptJavaSkeleton">

The **skeleton** is an empty BotWithUs script with the build setup already done. Cloning it means you don't have to set up Gradle, Maven, dependencies, or output paths by hand.

You can clone using either Git (if you know it) or directly through IntelliJ. The IntelliJ way is easier.

#### Cloning through IntelliJ

1. From the IntelliJ welcome screen, click **Clone Repository** (or **File → New → Project from Version Control** if a project is already open).
2. In the **URL** field, paste:
```
https://github.com/BotWithUs/BwuScriptJavaSkeleton
```
3. Pick a folder for it (default is fine).
4. Click **Clone**.

IntelliJ will download the project and ask if you want to **trust** it — say **Trust Project**. It'll then start indexing files (bottom status bar). Wait for indexing to finish before doing anything else.

#### If IntelliJ asks about Git

If IntelliJ says *"Git is not installed"* and you don't already have it: install it from [git-scm.com](https://git-scm.com/), accept all defaults, and try the clone again. Git is also useful later if you want to track your changes, and it's a must-have for publishing scripts to the marketplace.

</BrowserWindow>
</ContentBlock>

<ContentBlock title="Step 3 — Download JDK 20 from inside IntelliJ">

You don't need to fetch a JDK from the web — IntelliJ has a built-in dialog. With the skeleton project open:

1. Go to **File → Project Structure** (or `Ctrl+Alt+Shift+S`).
2. On the left, click **Project**.
3. Find the **SDK** dropdown. If it's blank or shows the wrong version, click it → **Download JDK…**.
4. In the dialog:
- **Version:** 20
- **Vendor:** any works, but **Eclipse Temurin** or **Amazon Corretto** are common safe choices.
- **Location:** leave the default.
5. Click **Download**. IntelliJ pulls the JDK and selects it for the project.
6. Set **Language level** to **SDK Default**.
7. Click **OK**.

</ContentBlock>

<ContentBlock title="Step 4 — Confirm Gradle loaded the project">

The skeleton uses **Gradle** (Kotlin DSL — `build.gradle.kts`) to manage its dependencies. IntelliJ should detect this automatically and start a Gradle sync as soon as the project opens.

- Look for a **Gradle** tool window on the right edge of IntelliJ. Click it.
- You should see the project with sections like **Tasks** (with `build`, `assemble`, etc.) and **Dependencies**.
- If a yellow banner at the top of the editor says *"Gradle project needs to be imported"* or *"Load Gradle Changes"* — click it (or press the refresh/sync icon in the Gradle tool window).

When indexing and the Gradle sync finish, the bottom status bar goes quiet. You're ready.

</ContentBlock>

<ContentBlock title="Step 5 — Sanity check: open the main script file">

In the **Project** tool window (left edge):

1. Expand `src` → `main` → `java` → `net.botwithus...` (the package path varies by skeleton version).
2. Find the `.java` file — it'll be the one with the same name as the skeleton's main class.
3. Double-click to open.

:::info This is just a folder structure
What you see in the **Project** tool window is the same folder layout that exists on disk. IntelliJ collapses Java packages into a single dotted entry (e.g. `net.botwithus.example`) for readability, but if you open the project folder in Windows Explorer you'll find real, nested folders: `src\main\java\net\botwithus\example\`. Each `.` in the package name is a folder boundary on disk.
:::

If the editor shows code with **no red squiggles**, the IDE, JDK, and dependencies are all happy. You're ready to build it into a real script.

:::warning If there are red squiggles everywhere
That usually means Gradle hasn't finished syncing or the JDK isn't set. Re-check Step 3 and Step 4. Still stuck? Post a screenshot in the [public scripters channel](https://discord.com/channels/973830420858810378/1257291849475817565) on Discord.
:::

</ContentBlock>

**Next:** [build the skeleton into your first running script →](./05-first-script.md)
Loading
Loading