workspace API

Workspace API

Workspace variables

Workspace contains variables that you use in current script session. These variables are stored as long as workspace exists. You can work with workspace variables in scripts: To place a variable in a workspace, you do not need to declare it.

foo = "bar"
println foo // bar

Also, there is a second way to do this: Set variable as property of workspace

workspace.baz = "qux"; set property of workspace
workspace.setProperty("answer",42) // a similar effect
println baz // qux
println answer // 42
println workspace.baz // qux
println workspace.getProperty("answer") // 42

This way also allows you to set variables in another workspace. Remove variable:

workspace.getBindings().getVariables().remove("foo")
workspace.removeProperty("foo") // since v1.1.2

Global variables

Global variables available in all scripts, even in the different workspace environment. To set the value of a variable, you must set a property of the global object

global.perfectLocation = world[100,80,200]
// now perfectLocation awailable for all players and all scripts
me >> perfectLocation // teleport you to location world:100:80:200
me >> global.perfectLocation // similar

Workspace variables has a higher priority. Example:

workspace.t = "In workspace"
global.t = "In global"
println t // in workspace
println workspace.t // in workspace
println global.t // in global

Register events

Bukkit event registration system is not suitable for scripting. Workspace API allows you to register listeners anywhere and easy:

def blockListener = workspace.listen { BlockBreakEvent event ->
   // - listener code here -
}

or so:

def blockListener = workspace.listen(BlockBreakEvent) { event ->
   // - listener code here -
}

When you specify an event handler, you can reference to method:

void onBlockBreak(BlockBreakEvent event) {
   // - event handler here -
}
def blockListener = workspace.listen( this.&onBlockBreak )

You can register events with parameters priority:EventPriority and ignoreCancelled:boolean. This parameters is optional.

workspace.listen(EventPriority.LOWEST,true){ PlayerInteractEvent event ->
   // - listener code here -
}
workspace.listen(PlayerInteractEvent,EventPriority.LOWEST,true){ event ->
   // - listener code here -
}

You can stop the listener in any time:

blockListener.stop() // true on success

and check listener state:

blockListener.stopped // true if listener is stopped

you can omit the workspace parameter. Listener will be registered in current workspace

listener = listen (PlayerChatEvent) { /* ... */ }

Register timers

Workspace can schedule a tasks better than BukkitScheduler. In fact, it just adds syntactic sugar.

def timer = workspace.timeout(500) {
    // elapsed 500 ticks
}
def timer2 = workspace.timeout(500, false) {
    // elapsed 500 ticks, run asynchronously
}

run repeating task:

def interval = workspace.interval(100) {
    // run every 100 ticks
}
def interval2 = workspace.interval(100, 50) {
    // run every 10 ticks, first delay is 50 ticks
}
def interval3 = workspace.interval(100, 50, false) {
    // run ... asynchronously
}

timers stops automatically after execution. stop repeating task or forcibly stop timer:

timer.stop() // true on success
timer.stopped // check state
interval.stop()
interval.stopped

You can use iteration variable in intervals:

def interval = workspace.interval(100) { int i ->
    // each loop iteration i nincreaced by 1. Starting value is 0.
}

Or someone interesting: pass this interval into closure

workspace.interval(100) { int i, def interval ->
    // do sonething with i
    if (i >= 5) interval.stop()
}

Execute task when workspace is stopped

You can hook into the process of stopping the workspace:

def hook = workspace.stopHook {
    println "OH NO! Workspace is stopped"
}

this code will be executed when workspace is stopped:

• by commands /workspace stop, /workspace remove, /workspace reload
• on disable plugin
• on shutdown server If you no longer need this path, you can stop it:

hook.stopped // check state
hook.stop() // stop it

Commands

Workspace can dynamically register command executors

// set name, description, usage and aliases
commandTest = workspace.command("Test","1st test","Usage: /test",[]) {
    CommandSender sender, List<String> args ->
    sender.sendMessage "This is a 1st test command. Enjoy! Arguments: $args"
    return true
}
commandTest2 = workspace.command(
    name: "Test2", // required
    description: "Second test command", // optional
    usage: "Usage: /test2 ...args", // optional
    aliases: ["t2"], // optional
    handler: { CommandSender sender, List<String> args, String command ->
        if (!arguments) return false;
        sender.sendMessage "2nd test command. Arguments: $args"
        return true;
    }  /* required */
)

Remove created commands:

commandTest.stop()

Grouping events, hooks, commands and timers

Workspace allows you to create a generator which can work with listeners, timers and hooks too, as workspace:

def generator = workspace.generator()
generator.interval(100) { /* do something */ }
generator.listen(PlayerChatEvent) { /* do something */ }

It's great that you can stop all tasks created by generator:

generator.stop()

generator stops automatically when workspace is stopped. You can create a generators chain of any length.

Manage workspaces

Get all working workspaces:

global.getWorkspaces() // returns Workspace[]

Get workspace by name:

global.getWorkspace("CityTeleporter") // returns Workspace or null

Create a new workspace:

global.getOrCreateWorkspace("CityTeleporter") // returns Workspace

Remove workspace:

workspace.removeWorkspace()