Skip to main content

​
Your First Script

This guide will walk you through creating your first Skript - a simple join/leave message system with a custom command. By the end, you’ll understand the basics of events, commands, and variables.
Make sure you’ve installed Skript before starting this guide.

​
Create a New Script File

1

Create the file

Navigate to your server’s plugins/Skript/scripts/ folder and create a new file called welcome.sk.
Script files must have the .sk extension to be recognized by Skript.
2

Add welcome messages

Open welcome.sk in your text editor and add the following code:
# Welcome players with custom join/leave messages
on join:
    set the join message to "Oh look, %player% joined! :)"

on quit:
    set the quit message to "Oh no, %player% left! :("
This script listens for join and quit events and customizes the messages shown to all players.
3

Load the script

In your server console or as an admin in-game, run:
/skript reload welcome
You should see a message confirming the script loaded successfully. Now try disconnecting and rejoining - you’ll see your custom messages!

​
Understanding the Basics

​
Events

Events are triggers that run code when something happens. In our example: 
on join:
    # Code here runs when a player joins
Common events include:
  • on join - Player joins the server
  • on quit - Player leaves the server
  • on death - Entity dies
  • on break - Block is broken
  • on command - Command is executed

​
Effects

Effects are actions that change something. For example: 
set the join message to "Welcome %player%!"
broadcast "Server is restarting!"
give player a diamond sword

​
Expressions

Expressions represent values that can be used in your scripts:
  • %player% - The player who triggered the event
  • %victim% - In damage events, the entity being damaged
  • %now% - The current time
  • %location of player% - A player’s current location

​
Add a Custom Command

Let’s expand our script with a command that allows players to see how long they’ve been playing. Add this to your welcome.sk file: 
# Track when players join and let them check their playtime
on join:
    set the join message to "Oh look, %player% joined! :)"
    set {join.time::%uuid of player%} to now

on quit:
    set the quit message to "Oh no, %player% left! :("

command /playtime:
    description: Check how long you've been playing this session
    executable by: players
    trigger:
        if {join.time::%uuid of player%} is set:
            send "You've been playing for %time since {join.time::%uuid of player%}%!"
        else:
            send "Unable to determine your playtime."
Reload the script: 
/skript reload welcome
Now players can use /playtime to see how long they’ve been online!

​
Understanding the Command

Let’s break down the command structure: 
command /playtime:
    description: Check how long you've been playing this session
    executable by: players
    trigger:
        # Command code goes here
  • command /playtime: - Defines a new command
  • description: - Shown in /help
  • executable by: players - Only players can run it (not console)
  • trigger: - Code that runs when the command is used

​
Variables

We used {join.time::%uuid of player%} to store data:
  • Variables start with { and end with }
  • %uuid of player% makes it unique per player
  • Variables persist between server restarts
  • List variables use :: notation

​
Create a More Complex Example

Let’s create a new script called heal.sk with command arguments and permissions: 
command /heal [<player>]:
    description: Heal yourself or another player
    permission: skript.heal
    permission message: You don't have permission to use this command!
    executable by: players
    trigger:
        if arg-1 is set:
            # Heal another player (requires admin permission)
            if player has permission "skript.heal.others":
                heal arg-1
                set the food level of arg-1 to 10
                send "You healed %arg-1%!" to player
                send "You were healed by %player%!" to arg-1
            else:
                send "You don't have permission to heal others!"
        else:
            # Heal yourself
            heal player
            set the food level of player to 10
            send "You have been healed!"
This command:
  • Accepts an optional player argument
  • Requires the skript.heal permission
  • Allows healing others with skript.heal.others permission
  • Heals health and hunger
  • Sends feedback messages

​
Working Example: Welcome Kit

Here’s a complete working script that gives new players a starter kit: 
# Give new players a welcome kit
on first join:
    broadcast "Welcome %player% to the server for the first time!"
    
    # Give starter items
    give player a stone sword named "Starter Sword"
    give player 16 cooked beef
    give player 32 oak planks
    
    # Set spawn point
    set the player's spawn point to location(0, 65, 0, world "world")
    
    # Send welcome message
    send "" to player
    send "&6&l========== WELCOME! ==========" to player
    send "" to player  
    send "&eThank you for joining!" to player
    send "&eType &a/help &eto get started." to player
    send "" to player
    send "&6&l==============================" to player
    send "" to player
Save this as starterkit.sk and reload: 
/skript reload starterkit
The & symbol followed by a color code (like &6 for gold or &e for yellow) adds color to text. Use &l for bold formatting.

​
Code Examples from Source

These examples are adapted from Skript’s official example scripts found in the source repository: 
# Custom damage handling
on damage:
    victim is a player
    if the victim has permission "skript.example.damage":
        cancel the event  # Stops the default behaviour
    else:
        send "Ouch! You took %damage% damage." to the victim
        add damage to {damage::%uuid of victim%::taken}
        if the attacker is a player:
            add damage to {damage::%uuid of attacker%::dealt}

​
Next Steps

Now that you’ve created your first scripts, here’s what to explore next:

Core Concepts

Deep dive into how Skript works

Events Reference

Learn about all available events

Variables Guide

Master data storage and persistence

Command Guide

Create advanced custom commands

​
Common Patterns

if player has permission "my.permission":
    send "You have permission!"
else:
    send "You don't have permission!"

if player's health is less than 5:
    send "You're low on health!"

if player's level is greater than or equal to 10:
    send "You're experienced!"

on break:
    event-block is a diamond ore
    player's tool is a iron pickaxe or diamond pickaxe
    send "You found diamonds with a good pickaxe!"

give player 64 stone, 32 dirt and an apple

remove a diamond from player's inventory

player's inventory contains a sword

​
Tips for Success

Debugging: If your script doesn’t work, check the server console for error messages. Skript provides detailed error information including line numbers.
Testing: Use /skript reload <scriptname> frequently while developing. You don’t need to restart your server to test changes!
Be careful with loops: Infinite loops can freeze your server. Always include a way to exit loops or use delays in loops that run many times.

Build docs developers (and LLMs) love

Get started for freeTalk to us