Functions

Functions allow you to organize code into reusable blocks that can be called from anywhere in your scripts. They accept parameters and can return values.

Basic Function Syntax

Define a function with the function keyword:

function <name>(<parameters>):
	# function code here

Call a function by name:

<function-name>(<arguments>)

Simple Function Example

Here’s a basic broadcasting function:

#
# A simple broadcasting function example.
# This demonstrates how to declare and run a simple function.
#

function say_message(message: text):
	broadcast {_message} # our message argument is available in `{_message}`.

on first join:
	wait 1 second
	say_message("Welcome, %player%!") # Runs the `say_message` function.

Function parameters are available as local variables with an underscore prefix: {_parameter_name}

Function Parameters

Functions can accept multiple parameters of different types:

function give_apple(name: text, amount: number) :: item:
	set {_item} to an apple
	set the name of {_item} to {_name}
	set the item amount of {_item} to {_amount}
	return {_item} # Gives this value to the code that called the function.

command /appleexample:
	permission: skript.example.apple
	trigger:
		send "Giving you an apple!"
		set {_item} to give_apple("Banana", 4)
		give player {_item}

Parameter Types

Specify the type for each parameter:

function example(message: text):
function example(amount: number):
function example(target: player):
function example(loc: location):
function example(item_type: item):

Return Values

Functions can return a value using :: <type> and the return statement:

function give_apple(name: text, amount: number) :: item:
	set {_item} to an apple
	set the name of {_item} to {_name}
	set the item amount of {_item} to {_amount}
	return {_item}

The return type comes after :: in the function declaration. Use return <value> to send a value back to the caller.

Using Return Values

# Store the returned value
set {_custom_item} to give_apple("Golden Apple", 5)
give player {_custom_item}

# Use directly
give player give_apple("Silver Apple", 1)

# Use in conditions
if get_balance(player) > 100:
	send "You have enough money!"

Recursive Functions

Functions can call themselves for complex operations:

#
# An example of a recursive (self-calling) function that is used to repeat a complex task.
# Please note that self-calling functions can loop infinitely, so use with caution.
#

function destroy_gold(source: block) :: blocks:
	add {_source} to {_found::*}
	break {_source} naturally using an iron pickaxe
	loop blocks in radius 1 of {_source}:
		loop-block is a gold ore block
		break loop-block naturally using an iron pickaxe
		if {_found::*} does not contain loop-block:
			add destroy_gold(loop-block) to {_found::*}
	return {_found::*}

command /oreexample:
	permission: skript.example.ore
	trigger:
		if the player's target block is a gold ore block:
			send "Destroying all connected ore."
			set {_found::*} to destroy_gold(player's target block)
			send "Destroyed %size of {_found::*}% connected ores!"
		else:
			send "<red>You must be looking at an ore block!"

Recursive functions can cause infinite loops if not properly designed. Always include a base case that stops the recursion.

Function Scope

Functions can access:

Parameters: Available as {_parameter_name}
Local variables: Created within the function
Global variables: Accessible everywhere

function example(input: text):
	set {_local} to {_input} # Parameter as local variable
	set {global} to {_input} # Global variable
	# {_local} is deleted when function ends
	# {global} persists

Return Types Reference

Common return types:

Basic Types

:: text - Returns text/string
:: number - Returns a number
:: boolean - Returns true/false
:: timespan - Returns a duration

Game Objects

:: player - Returns a player
:: entity - Returns an entity
:: item - Returns an item
:: block - Returns a block
:: location - Returns a location

Collections

:: items - Returns multiple items
:: blocks - Returns multiple blocks
:: players - Returns multiple players
:: texts - Returns multiple texts

Function Organization

Separate Function File

Create a dedicated file for shared functions:

functions.sk

# Helper functions used across multiple scripts

function format_money(amount: number) :: text:
	return "$%{_amount}%"

function has_balance(target: player, amount: number) :: boolean:
	if {balance::%uuid of {_target}%} >= {_amount}:
		return true
	return false

function deduct_balance(target: player, amount: number):
	remove {_amount} from {balance::%uuid of {_target}%}

Using Functions Across Scripts

Functions are accessible from any script after being loaded:

shop.sk

command /buy <item>:
	trigger:
		set {_price} to 10
		if has_balance(player, {_price}):
			deduct_balance(player, {_price})
			give arg-1 to player
			send "Purchased for %format_money({_price})%"
		else:
			send "You need %format_money({_price})%!"

Function Best Practices

Single Responsibility

Each function should do one thing well. Break complex logic into multiple functions.

Clear Names

Use descriptive names like give_apple() not ga(). Names should explain what the function does.

Type Parameters

Always specify parameter types for clarity and error prevention.

Return Early

Return as soon as you have a result to avoid unnecessary processing.

Error Handling

Validate inputs in your functions:

function teleport_safely(target: player, destination: location):
	if {_target} is not set:
		return # Exit if no player
	if {_destination} is not set:
		return # Exit if no location
	
	# Check if destination is safe
	if block at {_destination} is lava:
		send "Cannot teleport to lava!" to {_target}
		return
	
	teleport {_target} to {_destination}

Complete Function Examples

Item Creator Function

function create_custom_item(name: text, type: item, lore_text: text) :: item:
	set {_item} to {_type}
	set name of {_item} to {_name}
	set line 1 of lore of {_item} to {_lore_text}
	return {_item}

command /customitem:
	trigger:
		set {_sword} to create_custom_item("Legendary Sword", diamond sword, "A powerful weapon")
		give {_sword} to player

Balance System Functions

function get_balance(target: player) :: number:
	return {balance::%uuid of {_target}%} ? 0

function set_balance(target: player, amount: number):
	set {balance::%uuid of {_target}%} to {_amount}

function add_balance(target: player, amount: number):
	add {_amount} to {balance::%uuid of {_target}%}

function has_balance(target: player, amount: number) :: boolean:
	if get_balance({_target}) >= {_amount}:
		return true
	return false

command /balance:
	trigger:
		send "Your balance: $%get_balance(player)%"

aliases:
	menu items = TNT, lava bucket, string, coal, oak planks

function make_menu(name: text, rows: number) :: inventory:
	set {_gui} to a new chest inventory with {_rows} rows with name {_name}
	loop {_rows} * 9 times: # Fill the inventory with random items.
		set slot loop-number - 1 of {_gui} to random item out of menu items
	return {_gui}

command /fancymenu:
	permission: skript.example.menu
	trigger:
		set {_menu} to make_menu("hello", 4)
		add {_menu} to {my inventories::*} # Prepare to listen to this inventory.
		open {_menu} to player

on inventory click: # Listen for players clicking in any inventory.
	if {my inventories::*} contains event-inventory: # Make sure it's our menu.
		cancel event
		send "You clicked slot %index of event-slot%!"

on inventory close: # No longer need to listen to this inventory.
	{my inventories::*} contains event-inventory
	remove event-inventory from {my inventories::*}

Function Performance

Functions have minimal performance overhead in Skript. Don’t hesitate to use them to organize your code.

Performance tips:

Use local variables for temporary data
Return early to avoid unnecessary processing
Cache expensive calculations in variables
Avoid recursive functions for simple tasks

Debugging Functions

Add debug messages to track function execution:

function debug_example(value: text):
	broadcast "[DEBUG] Function called with: %{_value}%"
	set {_result} to {_value}
	broadcast "[DEBUG] Function returning: %{_result}%"
	return {_result}

Common Patterns

function is_valid_player(target: player) :: boolean:
	if {_target} is not set:
		return false
	if {_target} is not online:
		return false
	return true

Get Started

Core Concepts

Guides

Advanced

Basic Function Syntax

Simple Function Example

Function Parameters

Parameter Types

Return Values

Using Return Values

Recursive Functions

Function Scope

Return Types Reference

Function Organization

Separate Function File

Using Functions Across Scripts

Function Best Practices

Single Responsibility

Clear Names

Type Parameters

Return Early

Error Handling

Complete Function Examples

Item Creator Function

Balance System Functions

Menu Builder Function

Function Performance

Debugging Functions

Common Patterns

Next Steps

Variables

Commands

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Advanced

​Basic Function Syntax

​Simple Function Example

​Function Parameters

​Parameter Types

​Return Values

​Using Return Values

​Recursive Functions

​Function Scope

​Return Types Reference

​Function Organization

​Separate Function File

​Using Functions Across Scripts

​Function Best Practices

Single Responsibility

Clear Names

Type Parameters

Return Early

​Error Handling

​Complete Function Examples

​Item Creator Function

​Balance System Functions

​Menu Builder Function

​Function Performance

​Debugging Functions

​Common Patterns

​Next Steps

Variables

Commands

Build docs developers (and LLMs) love

Basic Function Syntax

Simple Function Example

Function Parameters

Parameter Types

Return Values

Using Return Values

Recursive Functions

Function Scope

Return Types Reference

Function Organization

Separate Function File

Using Functions Across Scripts

Function Best Practices

Error Handling

Complete Function Examples

Item Creator Function

Balance System Functions

Menu Builder Function

Function Performance

Debugging Functions

Common Patterns

Next Steps