Home

Welcome to KotlinScript!

This project is primarily a SpongePowered plugin that enables scripts to run using the Spongepowered API

Writing a script

Scripts require a file extension of .plugin.kts -- ex: helloworld.plugin.kts

All scripts are written in Kotlin and have available the SpongeAPI and this projects API.

This would suffice as a valid; but sad, script. But we can do better! Below is an example of managing imports and using the logger (and comments)!

//Imports follow traditional Kotlin style
import me.zodd.Logger
//The API provides certain "Managers" for ease of use such as Logger!
Logger.info("Hello World!")

Very simple scripts that use this projects API, and certain bits of SpongeAPI may not require imports, but it's always best to provide them when possible.

//Import is not necessary, but is recommended
//import me.zodd.Logger
Logger.info("Hello World!")

Scripts have access to Events, and scripts can have multiple events in one file.

//We can also use wildcard imports
import me.zodd.*
import me.zodd.onServerStarted

//Scripts are evaluated during ConstructPluginEvent, so this method will run then.
Logger.info("Script Loaded!")
//Scripts can make use of many Events
onServerStarted {
    Logger.info("Server has started!")
}
//They can also make use of methods available to the event
onPlayerJoin {
    //ServerSideConnectionEvent.Join#player()
    val player = player()
    if (player.name().contentEquals("notch")) {
        player.kick()
    }
}

Scripts also have a way to write commands easily

import me.zodd.*
import net.kyori.adventure.text.Component
import org.spongepowered.api.command.parameter.CommonParameters

ScriptCommandManager {
    val playerParam = CommonParameters.PLAYER
    val reasonParam = CommonParameters.MESSAGE

    //This method creates a command named "kick" -- /kick
    command("kick") {
        //Permissions are optional, but notably the name of the command is provided in context -- $it
        permission = "plugin.command.$it" //plugin.command.kick
        //Aliases for the command, run it with /boot or /zap instead
        aliases += listOf("boot", "zap")
        
        //Parameters are added with the `+` sign.
        +playerParam
        +reasonParam
        //Commands will run the contents of this block during execution.
        executes {
            val reason = Component.text(requireOne(reasonParam))
            requireOne(playerParam).kick(reason)
            //Commands require a CommandResult
            //success() or error(Component)
            success()
        }
    }

    //You can write multiple commands
    command("...") {
        executes {
            success()
        }
    }
}

Loading scripts

To load a script and see all of its glory you simply need to ensure the plugin is on the server, and the script is placed at ./config/scripting-host/scripts/ in your server. If the script has any errors they will be displayed in the logs.

You can find this script with the other examples here. This script attempts to import org.invalid

Error Handling example

Writing these scripts with no IDE support?!

With the power of IntelliJ we have harnessed the power to bring you IDE support!

To make use of this feature is simple, you simply need to provide the script-runtime to the classpath in IntelliJ and the IDE should recognize the new script definitions and provide your scripts with proper support!

That sounds hard though!

Here's a template repo that you simply need copy and write scripts!