# Functions

{% hint style="info" %}
**"What is a function?"**

A function is a chunk of code that can be re-used or *called* from or executed by other code or even itself (recursion).

**"Why should I add functions to my script?"**

1. Re-usability: Functions allow you to write a block of code once, and then re-use it later. Rather than having repeated code, you can simply *call* the function in your scripts. Another amazing benefit of functions is parameters—values the calling code *passes in* to the function—allowing the function to perfectly integrate into a task each time it is called.
2. Readability: Reading function calls with descriptive names means it's easy to determine what the code is doing at that point. Since functions are re-usable, this also cuts down on the amount of code you'll need to read.
3. Maintainability: When you use a function, you have all of the 'work' being done in one place, which you can maintain or update. Otherwise, you'd have to change multiple instances.
   {% endhint %}

To create a new function, use the `function` keyword followed by the functions name, similar to a command: `command myCommand:` -> `function myFunction():`.

{% hint style="warning" %}
Functions are structures—meaning they cannot be defined within an event or command. You'll want to create a function first, as it's own independent structure, then call (use) it elsewhere. Notice in the below example that all the items are given within the function's body, and not in the events.
{% endhint %}

{% hint style="info" %}
Note the parentheses `()` after the function, these are where the *parameters* will go, similar to the arguments in a command: `command myCommand <arguments>:` -> `function myFunction(parameters):`.
{% endhint %}

{% code overflow="wrap" lineNumbers="true" %}

```python
#: Creating a function
function giveDefaultItems(player:player):
  give {_player} (iron sword)
  give {_player} (iron pickaxe)
  give {_player} (iron axe)
  give {_player} (64 of steak)

#: Using a function
on first join:
  giveDefaultItems(player)

on respawn:
  giveDefaultItems(player)
```

{% endcode %}

***

## Parameters

Parameters are specified with a name and datatype within the parentheses and are separated by commas: `function example(name-1:type-1, name-2:type-2):`.

Here's an example function that give a specific player a certain amount of cookies:

{% code overflow="wrap" lineNumbers="true" %}

```python
function giveCookies(player:player, amount:integer):
  give {_player} ({_amount} of cookie)
```

{% endcode %}

{% hint style="info" %}
The type of `object` allows a parameter to accept anything passed in.
{% endhint %}

These parameters are named `player` and `amount`, and they must be a `player` and an `integer` when the function is used. Parameters are accessed by local variables of the same name within the function, as seen on line 2.

To pass lists in to a function, pluralise the type:

{% code overflow="wrap" lineNumbers="true" %}

```python
function giveCookies(players:players, amount:integer):
  give {_players::*} ({_amount} of cookie)
```

{% endcode %}

Now the parameter accepts `players`, allowing for more than one player to be inputted. Also note that now the local variable `{_player}` has become the list `{_players::*}` to reflect that this may hold multiple values.

***

## Calling functions

When calling functions, pass in the values in the same order they are defined. So when calling this cookie function, pass in the players first and then the quantity of cookies.

{% hint style="info" %}
When using literal lists in function calls, parentheses must be used:

`giveCookies({_player-1}, {_player-2}, and {_player-3}, 5)` -> `giveCookies(({_player-1}, {_player-2}, and {_player-3}), 5)`. This is to let Skript know that all of those values should be treated as one parameter instead of each element being assigned to the next parameter. This issue is simplified with a list variable, which also makes the function call easier to read: `giveCookies({_players::*}, 5)`.
{% endhint %}

{% hint style="warning" %}
When calling, don't specify names, just values. For example, when calling the cookie function to give the player 10 cookies it should look like this: `giveCookies(player, 10)` and not `giveCookies(player:player, amount:10)`.
{% endhint %}

***

{% hint style="info" %}
**"But I only use this code here, so I shouldn't need a function"**

Even if you don't need to re-use a function, it still has the readability benefits and simplifies your code. If you only need a function within one script file, make it a local function by adding `local` to the start of the line. Local functions are only accessible within the file they are defined in.
{% endhint %}

{% hint style="warning" %}
Remember that a function cannot access data other than global variables; you'll need to pass in everything as parameters to use them within the function.
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://x8ight.gitbook.io/syntask/fundamentals/structures/functions.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.