Skip to content

getting started

Jump to bottom
github-actions[bot] edited this page Aug 6, 2026 · 1 revision

Getting Started

This guide will help you get up and running with YamlAnnotations quickly.

Installation

Gradle

plugins {
    id 'com.gradleup.shadow'
}

repositories {
    maven { url 'https://repo.codemc.io/repository/avarionmc/' }
}

dependencies {
    implementation 'org.avarion:yaml:VERSION'
}

jar {
    dependsOn shadowJar
}

Maven

<repositories>
    <repository>
        <id>codemc-repo</id>
        <url>https://repo.codemc.io/repository/avarionmc/</url>
    </repository>
</repositories>

<dependencies>
    <dependency>
        <groupId>org.avarion</groupId>
        <artifactId>yaml</artifactId>
        <version>VERSION</version>
    </dependency>
</dependencies>

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-shade-plugin</artifactId>
            <version>3.4.1</version>
            <executions>
                <execution>
                    <phase>package</phase>
                    <goals>
                        <goal>shade</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

Replace VERSION with the latest version from CodeMC.

Requirements

  • Java 17 or higher (required for Record support)
  • SnakeYAML 1.x or 2.x (automatically selected at runtime)

Your First Configuration Class

Step 1: Create a Configuration Class

Create a class that extends YamlFileInterface and annotate your fields:

import org.avarion.yaml.YamlFileInterface;
import org.avarion.yaml.YamlKey;

public class MyConfig extends YamlFileInterface {

    @YamlKey("server.name")
    public String serverName = "My Server";

    @YamlKey("server.port")
    public int port = 25565;

    @YamlKey("server.motd")
    public String motd = "Welcome!";
}

Step 2: Load or Save the Configuration

// Load configuration (creates file with defaults if it doesn't exist)
MyConfig config = new MyConfig().load("config.yml");

// Access values
System.out.println("Server: " + config.serverName);
System.out.println("Port: " + config.port);

// Modify and save
config.serverName = "Updated Server";
config.save("config.yml");

Step 3: The Generated YAML File

server:
  name: My Server
  port: 25565
  motd: Welcome!

Adding Comments

Use @YamlComment to add documentation to your configuration:

import org.avarion.yaml.YamlComment;
import org.avarion.yaml.YamlKey;

public class MyConfig extends YamlFileInterface {

    @YamlComment("The display name of your server")
    @YamlKey("server.name")
    public String serverName = "My Server";

    @YamlComment("Port number (1-65535)")
    @YamlKey("server.port")
    public int port = 25565;
}

Output:

server:
  # The display name of your server
  name: My Server

  # Port number (1-65535)
  port: 25565

Adding a File Header

Use the @YamlFile annotation to add a header comment:

import org.avarion.yaml.YamlFile;
import org.avarion.yaml.YamlFileInterface;
import org.avarion.yaml.YamlKey;

@YamlFile(header = """
    Server Configuration File
    Edit values below to customize your server.
    """)
public class MyConfig extends YamlFileInterface {

    @YamlKey("server.name")
    public String serverName = "My Server";
}

Output:

# Server Configuration File
# Edit values below to customize your server.

server:
  name: My Server

Minecraft Plugin Integration

For Minecraft plugins, you can load/save using the plugin instance:

@YamlFile(fileName = "config.yml")
public class PluginConfig extends YamlFileInterface {

    @YamlKey("settings.debug")
    public boolean debug = false;
}

// In your plugin's onEnable():
PluginConfig config = new PluginConfig().load(this);  // Uses plugin's data folder
config.save(this);

Next Steps

Clone this wiki locally