Configuration

Configuration files allow your plugin to store settings that users can modify. PocketMine-MP provides the Config class to easily work with YAML, JSON, and other formats.

Config File Formats

PocketMine-MP supports multiple configuration formats:

YAML (.yml) - Human-readable, most common
JSON (.json) - Structured data
Properties (.properties) - Key-value pairs
Serialized (.sl) - PHP serialized data

YAML is recommended for plugin configs because it’s easy to read and edit.

Default Config (config.yml)

Every plugin can have a default config.yml file.

Create resources/config.yml

Create a default config in your plugin’s resources folder:

resources/config.yml

# MyPlugin Configuration

# Enable plugin features
enabled: true

# Maximum players in game
max-players: 10

# Spawn location
spawn:
  world: world
  x: 0
  y: 64
  z: 0

# Messages
messages:
  welcome: "Welcome to the server!"
  goodbye: "See you later!"

# List of banned items
banned-items:
  - diamond_sword
  - tnt
  - bedrock

Load config in your plugin

src/MyPlugin/Main.php

<?php

declare(strict_types=1);

namespace MyPlugin;

use pocketmine\plugin\PluginBase;

class Main extends PluginBase {
    
    protected function onEnable() : void {
        // Save default config.yml if it doesn't exist
        $this->saveDefaultConfig();
        
        // Access config values
        $enabled = $this->getConfig()->get("enabled", true);
        $maxPlayers = $this->getConfig()->get("max-players", 10);
        
        $this->getLogger()->info("Enabled: " . ($enabled ? "yes" : "no"));
        $this->getLogger()->info("Max players: " . $maxPlayers);
    }
}

Reading Config Values

Simple Values

// Get a value (returns null if not found)
$value = $this->getConfig()->get("key");

// Get with default value
$value = $this->getConfig()->get("key", "default");

// Get specific types
$enabled = $this->getConfig()->get("enabled", true);  // boolean
$maxPlayers = (int) $this->getConfig()->get("max-players", 10);  // int
$message = (string) $this->getConfig()->get("welcome-message", "Hi");  // string

Nested Values

spawn:
  world: world
  x: 0
  y: 64
  z: 0

// Get nested value with dot notation
$world = $this->getConfig()->getNested("spawn.world", "world");
$x = (int) $this->getConfig()->getNested("spawn.x", 0);
$y = (int) $this->getConfig()->getNested("spawn.y", 64);
$z = (int) $this->getConfig()->getNested("spawn.z", 0);

// Or get entire section as array
$spawn = $this->getConfig()->get("spawn");
if(is_array($spawn)) {
    $world = $spawn["world"] ?? "world";
    $x = $spawn["x"] ?? 0;
}

Lists/Arrays

banned-items:
  - diamond_sword
  - tnt
  - bedrock

$bannedItems = $this->getConfig()->get("banned-items", []);

if(is_array($bannedItems)) {
    foreach($bannedItems as $item) {
        $this->getLogger()->info("Banned: " . $item);
    }
}

// Check if item is in list
if(in_array("tnt", $bannedItems, true)) {
    // TNT is banned
}

Get All Config Data

// Get all config as array
$allData = $this->getConfig()->getAll();

foreach($allData as $key => $value) {
    $this->getLogger()->info("$key = " . json_encode($value));
}

Writing Config Values

Set Values

// Set a value
$this->getConfig()->set("enabled", false);
$this->getConfig()->set("max-players", 20);

// Set nested value
$this->getConfig()->setNested("spawn.x", 100);
$this->getConfig()->setNested("spawn.y", 64);

// Save changes to disk
$this->getConfig()->save();

Changes to the config are only saved in memory until you call save()!

Add to Lists

$bannedItems = $this->getConfig()->get("banned-items", []);
$bannedItems[] = "flint_and_steel";
$this->getConfig()->set("banned-items", $bannedItems);
$this->getConfig()->save();

Remove Values

// Remove a key
$this->getConfig()->remove("old-setting");

// Remove nested key
$this->getConfig()->removeNested("spawn.y");

// Save
$this->getConfig()->save();

Reloading Config

// Reload from disk (discards unsaved changes)
$this->reloadConfig();

// Common pattern in reload command:
public function reloadPlugin() : void {
    $this->reloadConfig();
    $this->loadConfigValues();  // Re-read config values
    $this->getLogger()->info("Config reloaded!");
}

Custom Config Files

You can create additional config files beyond config.yml:

use pocketmine\utils\Config;

protected function onEnable() : void {
    // Save default messages.yml from resources
    $this->saveResource("messages.yml");
    
    // Load messages.yml
    $messagesFile = $this->getDataFolder() . "messages.yml";
    $messagesConfig = new Config($messagesFile, Config::YAML);
    
    $welcome = $messagesConfig->get("welcome", "Welcome!");
}

Using Multiple Configs

class Main extends PluginBase {
    
    private Config $messagesConfig;
    private Config $dataConfig;
    
    protected function onEnable() : void {
        // Main config
        $this->saveDefaultConfig();
        
        // Messages config
        $this->saveResource("messages.yml");
        $this->messagesConfig = new Config(
            $this->getDataFolder() . "messages.yml",
            Config::YAML
        );
        
        // Data config (JSON)
        $this->dataConfig = new Config(
            $this->getDataFolder() . "data.json",
            Config::JSON,
            ["players" => [], "games" => 0]  // defaults
        );
    }
    
    public function getMessage(string $key) : string {
        return $this->messagesConfig->get($key, "Message not found");
    }
    
    public function savePlayerData(string $name, array $data) : void {
        $players = $this->dataConfig->get("players", []);
        $players[$name] = $data;
        $this->dataConfig->set("players", $players);
        $this->dataConfig->save();
    }
}

Config File Formats

YAML Format

$config = new Config($file, Config::YAML);

enabled: true
max-players: 10
message: "Hello World"
list:
  - item1
  - item2
nested:
  key: value

JSON Format

$config = new Config($file, Config::JSON);

{
  "enabled": true,
  "max-players": 10,
  "message": "Hello World",
  "list": ["item1", "item2"],
  "nested": {
    "key": "value"
  }
}

Properties Format

$config = new Config($file, Config::PROPERTIES);

enabled=true
max-players=10
message=Hello World

Properties format only supports simple key-value pairs, no nesting or arrays.

Auto-Detect Format

// Automatically detect format by file extension
$config = new Config($file, Config::DETECT);

Complete Example: Game Plugin Config

# Game Plugin Configuration

# Enable the game
enabled: true

# Game settings
game:
  min-players: 2
  max-players: 10
  countdown: 30
  game-duration: 600

# Spawn locations
spawns:
  lobby:
    world: world
    x: 0
    y: 64
    z: 0
  game:
    world: game_world
    x: 100
    y: 64
    z: 100

# Rewards
rewards:
  winner:
    - diamond: 5
    - gold_ingot: 10
  participant:
    - iron_ingot: 3

# Messages
messages:
  game-start: "§aGame started!"
  game-end: "§eGame ended!"
  not-enough-players: "§cNot enough players"

Validating Config Values

private function loadConfigValues() : void {
    $this->maxPlayers = (int) $this->getConfig()->get("max-players", 10);
    
    // Validate
    if($this->maxPlayers < 1 || $this->maxPlayers > 100) {
        $this->getLogger()->warning(
            "Invalid max-players: {$this->maxPlayers}, using default 10"
        );
        $this->maxPlayers = 10;
    }
    
    // Validate nested value
    $world = $this->getConfig()->getNested("spawn.world");
    if(!is_string($world) || $world === "") {
        $this->getLogger()->error("Invalid spawn.world in config!");
        $this->getServer()->getPluginManager()->disablePlugin($this);
        return;
    }
}

Best Practices

Always provide defaults:

$value = $this->getConfig()->get("key", "default_value");

Validate user input:

if($value < 1 || $value > 100) {
    $this->getLogger()->warning("Invalid value, using default");
    $value = 10;
}

Save config in onDisable:

protected function onDisable() : void {
    $this->getConfig()->save();
}

Cache config values:

// Don't do this in hot code:
$max = $this->getConfig()->get("max-players");

// Instead, cache in onEnable:
private int $maxPlayers;

protected function onEnable() : void {
    $this->maxPlayers = (int) $this->getConfig()->get("max-players", 10);
}

Use type casting:

$maxPlayers = (int) $this->getConfig()->get("max-players");
$enabled = (bool) $this->getConfig()->get("enabled");
$message = (string) $this->getConfig()->get("message");

Get Started

Core Concepts

Plugin Development

Server Administration

Config File Formats

Default Config (config.yml)

Reading Config Values

Simple Values

Nested Values

Lists/Arrays

Get All Config Data

Writing Config Values

Set Values

Add to Lists

Remove Values

Reloading Config

Custom Config Files

Using Multiple Configs

Config File Formats

YAML Format

JSON Format

Properties Format

Auto-Detect Format

Complete Example: Game Plugin Config

Validating Config Values

Best Practices

Next Steps

Resources

Best Practices

Build docs developers (and LLMs) love

Get Started

Core Concepts

Plugin Development

Server Administration

​Config File Formats

​Default Config (config.yml)

​Reading Config Values

​Simple Values

​Nested Values

​Lists/Arrays

​Get All Config Data

​Writing Config Values

​Set Values

​Add to Lists

​Remove Values

​Reloading Config

​Custom Config Files

​Using Multiple Configs

​Config File Formats

​YAML Format

​JSON Format

​Properties Format

​Auto-Detect Format

​Complete Example: Game Plugin Config

​Validating Config Values

​Best Practices

​Next Steps

Resources

Best Practices

Build docs developers (and LLMs) love

Config File Formats

Default Config (config.yml)

Reading Config Values

Simple Values

Nested Values

Lists/Arrays

Get All Config Data

Writing Config Values

Set Values

Add to Lists

Remove Values

Reloading Config

Custom Config Files

Using Multiple Configs

Config File Formats

YAML Format

JSON Format

Properties Format

Auto-Detect Format

Complete Example: Game Plugin Config

Validating Config Values

Best Practices

Next Steps