Functions

Actionable and accessible members in a script.

Functions are a useful way to structure and re-use code, similar to Java methods. They are used to provide a lot of Skript's behaviour and functionality.

A simple introduction to their features is given below.

Function Structure

Functions can take a verifier and a trigger entry.

function example_function:
    verify:
        assert "hello" is a string
    trigger:
        print "hello"

Functions may also provide a return value, which is given back to the code that executed the function.

function example_function:
    trigger:
        if "hello" is a string:
            return 12
        return 64

An empty return effect will provide an empty null value to the executor.

function example_function:
    trigger:
        print "hello"
        return

Functions may accept named parameters, which are accessible inside that function as variables.

function example_function (number_1, number_2):
    trigger:
        print "The first number is: " + {number_1}
        return {number_1} + {number_2}

Function Use

Functions can be run directly in code, in the run effect.

run example_function
run example_function(1, 2)

If the result of a function is needed, it can be used as an expression.

set {var} to example_function(1, 2)

This means that functions can be used to run each other.

function first: // This function has no parameters, so we don't need the ( )
    trigger:
        set {var} to 1
        set {result} to add_together({var}, 3)
        print "The result is: " + {result}

function add_together (number_1, number_2):
    trigger:
        return {number_1} + {number_2}

Functions can be used to do repetitive actions, to avoid writing the same code multiple times.

function write_file (name, value):
    trigger:
        set {file} to a new file at {name} + ".txt"
        set the contents of {file} to {value}

function get_file (name):
    trigger:
        set {file} to the file at {name} + ".txt"
        return the contents of {file}

function my_function:
    trigger:
        write_file("test", "hello there") // calls our write function
        set {contents} to get_file("test") // uses our get function
        assert {contents} is "hello there" // checks it matches
        print {contents} // prints the contents
        delete the file at "test.txt" // gets rid of our file

Remote Function use

Functions from other scripts are also available, but need to be run using a special syntax.

The target script is specified according to its file path from the code folder (called skript by default.) A file called my_script would be found at skript/my_script.

run example_function(1, 2) from skript/my_other_skript

Dynamic Function Use

Occasionally, functions may need to be run when you do not know their name. The dynamic function expression can be used for this.

function test_function:
    trigger:
        set {func} to function "my_target"
        run {func} with "hello"

function my_target:
    trigger:
        print "hello"

This expression provides a handle or function 'object', rather than the value of the function. It is slightly slower than using the function directly, but not by a significant amount.

The handle is provided by Mirror, an advanced dynamic call library for the JVM.

As the handle is found by string pattern, this could be assembled from variables or function parameters.

The parameter indicators in the function string are only placeholders for clarity.

function test_function:
    trigger:
        set {func} to function "my_target(a, b)"
        set {func} to function "my_target(thing1, thing2)"
        // the parameter count is important, not the value
        run {func} with ("hello ", "there")

function my_target(a, b):
    trigger:
        print {a} + {b}

Running a dynamic function with a single argument can be done by providing it.

set {func} to function "my_target(var)"
run {func} with "hello"

Running a function with multiple arguments can be done using an implicit array.

set {func} to function "my_target(a, b, c)"
run {func} with (1, 2, {var})

It may also be run using a list of the arguments.

set {list} to a new list
add 1 to {list}
add "hello" to {list}
set {func} to function "my_target(a, b)"
run {func} with {list} // this is smartly unpacked to (1, "hello")

There is a rare occasion where your only argument for the function must be a list, and you do not want the list to be unpacked. In this case you must use the explicit array creator.

set {arg} to a new array ({list})
set {func} to function "my_target(thing)"
run {func} with {arg} // this is an array of one thing

This is because the implicit array creator cannot take only one argument - that would be the bracket expression instead!

External functions can also be obtained dynamically.

set {func} to function "my_target(thing) from skript/my_other_script"
run {func} with "hello"

Return Types

A function may specify an explicit return type of what it will give back to the trigger that ran it.

function test:
    return: string
    trigger:
        return "hello"

This is unnecessary for most programs, but can help to prevent unexpected errors. Specifying a return type will allow only that type to be returned from the function. Returning the wrong value will error.

This is designed for programs that wish to override Java methods.

Return None

Functions may specify none as a return type if they have no result value. If this is specified, the return %Object% effect may not be used.

If a trigger tries to get a return value from this function, it will get an empty null value.

The none return type counts as a Java void.

Parameter Types

Functions may specify one or more explicit types for their parameters.

function test (a, b):
    parameters: string, integer
    trigger:
        assert {a} is a string
        assert {b} is a number
        loop {b} times:
            print {a}

If a function has explicit type parameters, the arguments are guaranteed to be of this type. The Skript runtime will attempt to convert incorrect values (e.g. "3" -> 3) but if there is no available converter an error will be given instead.

function test (name, age):
    parameters: string, integer
    trigger:
        print {name} + " is " + {age} + " years old."

run test("Henry", 92)
run test("Paula", "31") // "31" -> 31
run test(3.5, 4) // 3.5 -> "3.5"

Libraries may register additional type converters.