Project setup

A Java script is a small Gradle project that builds one JAR. The JAR is a Java module that provides one or more BotScript implementations. The Java host finds them when it scans its scripts folder.

What you need

• JDK 25. The BotWithUs framework itself builds with a Java 25 toolchain, so target 25.
• Gradle with the Kotlin DSL (build.gradle.kts).
• An IDE that understands Gradle, such as IntelliJ IDEA.

build.gradle.kts

The script API is published as com.botwithus:bot-api to a public Maven repository. It needs no login or token.

plugins {
    java
}

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(25)
    }
}

repositories {
    mavenCentral()
    maven { url = uri("https://botwithus.github.io/maven") }
}

dependencies {
    compileOnly("com.botwithus:bot-api:1.5.0")
}

• Use the newest bot-api version listed in the repository. Published versions never change, so a fix always arrives as a new version.
• Declare the API as compileOnly. The host already has it at runtime, and a second copy inside your JAR causes trouble (see Preparing for SDN).
• SLF4J comes with the API. You do not need to add a logging dependency.
• Sources and Javadoc are published next to each release, so your IDE shows documentation and lets you step into the API.

If your script draws its own UI (see API tour), add ImGui as compile-only too. The host loads ImGui itself:

dependencies {
    compileOnly("com.botwithus:bot-api:1.5.0")
    compileOnly("io.github.spair:imgui-java-binding:1.90.0")
}

module-info.java

Every script JAR is a Java module. It must require the API and declare that it provides BotScript:

module my.script {
    requires com.botwithus.bot.api;
    provides com.botwithus.bot.api.BotScript with my.script.MyScript;
}

With a UI, also require ImGui:

module my.script {
    requires com.botwithus.bot.api;
    requires imgui.binding;
    provides com.botwithus.bot.api.BotScript with my.script.MyScript;
}

One JAR can provide several scripts. List them after with, separated by commas.

The services file

Also add src/main/resources/META-INF/services/com.botwithus.bot.api.BotScript. It lists the full class name of each script, one per line:

my.script.MyScript

The host loads your JAR as a module, so provides in module-info.java is what it reads. You still need the services file for a Script Market JAR, so keep both in step from the start. Preparing for SDN explains why.

Build and install

gradle build (or ./gradlew build with a wrapper) writes the JAR to build/libs/. Copy it into the Java host's scripts folder, ~/.botwithus/scripts. If the host's working directory has a scripts folder of its own, the host uses that one instead.

The framework's own example project adds a small task that copies the JAR after every build:

tasks.register<Copy>("installScript") {
    dependsOn(tasks.jar)
    from(tasks.jar.get().archiveFile)
    into(file(System.getProperty("user.home") + "/.botwithus/scripts"))
}

tasks.named("build") {
    finalizedBy("installScript")
}

Next: A complete example.