Home

Welcome to the wiki for Cotton Scripting, a datapack-focused scripting API for Fabric and Minecraft 1.15. It allows you to run any JSR-223-compatible scripting engine from commands and interact with the Minecraft world.

Importing into a Development Environment

Cotton Scripting is available on the Cotton maven. In your build.gradle, put:

repositories {
    maven { url 'http://server.bbkr.space:8081/artifactory/libs-snapshot }
}

dependencies {
  modCompile 'io.github.cottonmc:CottonScripting:<version>'
}

Writing Scripts

Scripts can be run using any JSR-223 script engine on the classpath. JavaScript is (at time of writing) natively included with Java 8 as the Nashorn library, though it is in the process of deprecation. Any other scripting language can be added if it has an implementation on JSR-223, but the jar may need a fabric.mod.json for it to be registered by the loader.

All scripts should be placed inside datapacks in the <namespace>/data/scripts/ folder, or any subfolder. Upon reload, they will be ready to call in-game. Scripts can either be called as a file, or you can call a specific function within the file. The script will be passed a CottonScript object named cotton, which carries information about the script's state, including any arguments passed by the user, and all functions called specifically will be passed a fresh context as a parameter. This is done because JSR-223 isn't too happy about having arbitrary amounts of arguments passed to a function. The CottonScript can also be used to send feedback to the user or run in-game commands.

Calling Scripts

Scripts can be run in-game with the /script command. It requires at least a permission level of 2, like with the vanilla /function command. The command requires the identifier of a script, and will autocomplete valid script files. Optionally, a specific method name can be passed, along with any arguments the player wants to send, separated by a comma and a space. Be warned: Scripts are arbitrary code. They are a lot more capable than standard mcfunctions, but that capability comes with a risk. Make absolutely sure you know what the scripts you put on your server do. Remember, all scripts are technically arbitrary code. Please make sure you don't download malware onto your or your players' computers.