SkriptYml Documentation

Introduction

SkriptYml is a powerful Skript addon that allows you to read, write, and delete data from YAML files directly in your Skript scripts. This addon simplifies data persistence without requiring database knowledge or complex file manipulation.

Version: 1.0-SNAPSHOT

Author: kbl/beklauter

Requirements: Skript 2.7.0+, Minecraft 1.21+

Simple Syntax

Easy-to-understand syntax for working with YAML data

High Performance

Optimized for Minecraft server environments

Flexible Storage

Support for complex nested data structures

Syntax

Reading Data

To read a value from a YAML file:

Skript

yaml value <key> from file <file path>

Example:

Skript

set {_playerData} to yaml value "players.%player's uuid%" from file "plugins/playerdata.yml"

Setting Data

To set a value in a YAML file:

Skript

set yaml value <key> in file <file path> to <value>

Example:

Skript

set yaml value "players.%player's uuid%.name" in file "plugins/playerdata.yml" to player's name

Deleting Data

To delete a value from a YAML file:

Skript

delete yaml value <key> from file <file path>

Example:

Skript

delete yaml value "players.%player's uuid%" from file "plugins/playerdata.yml"

Note: File paths are relative to your server directory. Make sure the directories exist or they will be created automatically.

Example Scripts

YAML Data Management Command

Create a command that can read, set, and delete values in a YAML file

View Example

Player Stats Tracker

Save player statistics to a YAML file for persistence across sessions

View Example

Player Homes System

Implement a complete homes system with YAML for data storage

View Example

YAML Data Management Command

This example creates a command that can read, set, and delete values in a YAML file:

Skript

command /yamldata <text> <text> [<text>]:
    usage: /yamldata <read|set|delete> <key> [<value>]
    description: Manage YAML data in the config file
    permission: yamldata.use
    executable by: players and console
    trigger:
        set {_file} to "plugins/yamldata/config.yml"
        set {_action} to arg-1
        set {_key} to arg-2

        if {_action} is "read":
            set {_value} to yaml value {_key} from file {_file}
            if {_value} is set:
                send "Value for key '%{_key}%': %{_value}%"
            else:
                send "Key '%{_key}%' doesn't exist in the file."

        else if {_action} is "set":
            if arg-3 is not set:
                send "Missing value. Usage: /yamldata set <key> <value>"
                stop
            set {_newValue} to arg-3
            set yaml value {_key} in file {_file} to {_newValue}
            send "Key '%{_key}%' has been set to '%{_newValue}%'"

        else if {_action} is "delete":
            delete yaml value {_key} from file {_file}
            send "Key '%{_key}%' has been deleted."

        else:
            send "Invalid action. Use 'read', 'set', or 'delete'."

Player Stats Tracker

This example saves player statistics to a YAML file:

Skript

on join:
    # Load or initialize player data
    set {_uuid} to player's uuid
    set {_file} to "plugins/playerstats/stats.yml"

    # Check if player exists in the file
    set {_joinCount} to yaml value "players.%{_uuid}%.joins" from file {_file}

    if {_joinCount} is not set:
        # New player
        set yaml value "players.%{_uuid}%.name" in file {_file} to player's name
        set yaml value "players.%{_uuid}%.joins" in file {_file} to 1
        set yaml value "players.%{_uuid}%.firstJoin" in file {_file} to now
    else:
        # Existing player
        set {_newCount} to {_joinCount} + 1
        set yaml value "players.%{_uuid}%.joins" in file {_file} to {_newCount}
        set yaml value "players.%{_uuid}%.lastJoin" in file {_file} to now

    # Send welcome message
    set {_name} to yaml value "players.%{_uuid}%.name" from file {_file}
    set {_joins} to yaml value "players.%{_uuid}%.joins" from file {_file}
    send "Welcome %{_name}%! This is your %{_joins}% time joining."

Player Homes System

This example implements a basic homes system using YAML storage:

Skript

command /sethome [<text>]:
    usage: /sethome [name]
    description: Set a home at your current location
    permission: homes.set
    trigger:
        set {_uuid} to player's uuid
        set {_file} to "plugins/homes/homes.yml"
        
        # Default home name if none provided
        set {_home} to "default"
        if arg-1 is set:
            set {_home} to arg-1
            
        # Get max homes limit
        set {_maxHomes} to 3 # Default limit
        set {_currentHomes} to yaml value "players.%{_uuid}%.homes" from file {_file}
        
        # If player already has homes, check limit
        if {_currentHomes} is set:
            set {_homesList::*} to {_currentHomes} split by ","
            if size of {_homesList::*} >= {_maxHomes} and {_homesList::*} does not contain {_home}:
                send "You've reached your maximum of %{_maxHomes}% homes."
                stop
        
        # Save home location
        set yaml value "players.%{_uuid}%.name" in file {_file} to player's name
        set yaml value "players.%{_uuid}%.home.%{_home}%.world" in file {_file} to player's world's name
        set yaml value "players.%{_uuid}%.home.%{_home}%.x" in file {_file} to player's x-coordinate
        set yaml value "players.%{_uuid}%.home.%{_home}%.y" in file {_file} to player's y-coordinate
        set yaml value "players.%{_uuid}%.home.%{_home}%.z" in file {_file} to player's z-coordinate
        set yaml value "players.%{_uuid}%.home.%{_home}%.yaw" in file {_file} to player's yaw
        set yaml value "players.%{_uuid}%.home.%{_home}%.pitch" in file {_file} to player's pitch
        
        # Update homes list
        if {_currentHomes} is not set:
            set yaml value "players.%{_uuid}%.homes" in file {_file} to {_home}
        else if {_homesList::*} does not contain {_home}:
            set yaml value "players.%{_uuid}%.homes" in file {_file} to "%{_currentHomes}%,%{_home}%"
            
        send "Home '%{_home}%' has been set!"

command /home [<text>]:
    usage: /home [name]
    description: Teleport to one of your homes
    permission: homes.teleport
    trigger:
        set {_uuid} to player's uuid
        set {_file} to "plugins/homes/homes.yml"
        
        # Default home name if none provided
        set {_home} to "default"
        if arg-1 is set:
            set {_home} to arg-1
            
        # Check if home exists
        set {_world} to yaml value "players.%{_uuid}%.home.%{_home}%.world" from file {_file}
        if {_world} is not set:
            send "Home '%{_home}%' doesn't exist!"
            stop
            
        # Get home location
        set {_x} to yaml value "players.%{_uuid}%.home.%{_home}%.x" from file {_file}
        set {_y} to yaml value "players.%{_uuid}%.home.%{_home}%.y" from file {_file}
        set {_z} to yaml value "players.%{_uuid}%.home.%{_home}%.z" from file {_file}
        set {_yaw} to yaml value "players.%{_uuid}%.home.%{_home}%.yaw" from file {_file}
        set {_pitch} to yaml value "players.%{_uuid}%.home.%{_home}%.pitch" from file {_file}
        
        # Teleport player
        teleport player to location({_x}, {_y}, {_z}, {_world}, {_yaw}, {_pitch})
        send "Teleported to home '%{_home}%'!"

command /delhome [<text>]:
    usage: /delhome [name]
    description: Delete one of your homes
    permission: homes.delete
    trigger:
        set {_uuid} to player's uuid
        set {_file} to "plugins/homes/homes.yml"
        
        # Default home name if none provided
        set {_home} to "default"
        if arg-1 is set:
            set {_home} to arg-1
            
        # Check if home exists
        set {_world} to yaml value "players.%{_uuid}%.home.%{_home}%.world" from file {_file}
        if {_world} is not set:
            send "Home '%{_home}%' doesn't exist!"
            stop
            
        # Delete home
        delete yaml value "players.%{_uuid}%.home.%{_home}%" from file {_file}
        
        # Update homes list
        set {_currentHomes} to yaml value "players.%{_uuid}%.homes" from file {_file}
        set {_homesList::*} to {_currentHomes} split by ","
        remove {_home} from {_homesList::*}
        
        if size of {_homesList::*} is 0:
            delete yaml value "players.%{_uuid}%.homes" from file {_file}
        else:
            set {_newList} to join {_homesList::*} with ","
            set yaml value "players.%{_uuid}%.homes" in file {_file} to {_newList}
            
        send "Home '%{_home}%' has been deleted!"

command /homes:
    description: List all of your homes
    permission: homes.list
    trigger:
        set {_uuid} to player's uuid
        set {_file} to "plugins/homes/homes.yml"
        
        # Get homes list
        set {_currentHomes} to yaml value "players.%{_uuid}%.homes" from file {_file}
        
        if {_currentHomes} is not set:
            send "You don't have any homes set."
            stop
            
        set {_homesList::*} to {_currentHomes} split by ","
        
        send "Your homes (%size of {_homesList::*}%):"
        loop {_homesList::*}:
            send "- %loop-value%"

Advanced Usage

Working with Lists

You can store lists in YAML files:

Skript

# Storing lists
set {_players::*} to ("Player1", "Player2", "Player3")
set yaml value "whitelist" in file "plugins/server.yml" to {_players::*}

# Reading lists
set {_storedPlayers::*} to yaml value "whitelist" from file "plugins/server.yml"
send "Whitelisted players: %{_storedPlayers::*}%"

Nested Structures

You can create complex nested data structures:

Skript

# Creating nested structures
set yaml value "server.regions.spawn.x1" in file "plugins/regions.yml" to 100
set yaml value "server.regions.spawn.y1" in file "plugins/regions.yml" to 64
set yaml value "server.regions.spawn.z1" in file "plugins/regions.yml" to 100
set yaml value "server.regions.spawn.x2" in file "plugins/regions.yml" to 200
set yaml value "server.regions.spawn.y2" in file "plugins/regions.yml" to 128
set yaml value "server.regions.spawn.z2" in file "plugins/regions.yml" to 200

# Reading nested structures
set {_x1} to yaml value "server.regions.spawn.x1" from file "plugins/regions.yml"
set {_y1} to yaml value "server.regions.spawn.y1" from file "plugins/regions.yml"
send "Spawn region starts at %{_x1}%, %{_y1}%"

File Operations

Additional file operations:

Skript

# Check if a file exists
if yaml file "plugins/config.yml" exists:
    send "Config file exists!"
else:
    send "Config file does not exist!"

# Load all keys from a section
set {_allKeys::*} to yaml keys "players" from file "plugins/playerdata.yml"
send "All player keys: %{_allKeys::*}%"

# Save a file (forces flush to disk)
save yaml file "plugins/config.yml"

Best Practices

Here are some recommendations for working effectively with SkriptYml:

Practice	Description
Use organized paths	Use namespaces like "player.stats.kills" instead of flat keys for better organization.
Save regularly	Use the "save yaml file" command after making multiple changes to ensure data persistence.
Error handling	Always check if values exist before using them to prevent errors.
Cache data	For frequently accessed data, store it in variables rather than reading from file repeatedly.
Back up files	Implement regular backup routines for important YAML files.

Warning: Be careful when deleting sections that contain many nested values. It's better to delete the parent key rather than individual nested keys when removing large structures.