pile

README

Pile

minimal world format for small worlds

Overview

Pile is a single-file world format and provider for Dragonfly server software. It targets small worlds, templates, and user-generated content. Each dimension is stored as a single .pile file with paletted blocks/biomes, optional Zstandard compression, and support for streaming/background saves.

Key Features

• Single-file per dimension
• Configurable compression: none, fast, default, best (Zstd)
• Paletted storage for blocks and biomes
• Full chunk data: blocks, biomes, entities, block entities, scheduled ticks
• Embedded world metadata (settings)
• Thread-safe provider with read/write locks
• Background and streaming saves to reduce stalls/peak memory

Installation

Use Go modules:

• go get github.com/oriumgames/pile

Quick Start

• Create a provider: provider, err := pile.New("world")
• Use in a world config: world.Config{Provider: provider}
• Assign the provider to your world/server config before starting
• Save on shutdown: defer provider.Close()

Options

• Compression:
  • New with level: pile.NewWithCompression(dir, pile.CompressionLevelDefault)
  • Change later: provider.SetCompressionLevel(pile.CompressionLevelBest)
• Read-only mode:
  • pile.NewReadOnly(dir) or pile.NewReadOnlyWithCompression(dir, level)
  • Prevents all modifications, useful for inspection or analysis
• Streaming saves:
  • provider.SetStreamingSaves(true) to write chunk-by-chunk
• Background saves:
  • provider.EnableBackgroundSaves() then trigger with provider.SaveAsync()
  • Stop with provider.DisableBackgroundSaves()
• Introspection:
  • provider.ChunkCount(), provider.DimensionChunkCount(world.Overworld), provider.IsDirty(), provider.IsReadOnly()

File Layout

World directory (created as needed):

• overworld.pile — Overworld data
• nether.pile — Nether data (only if present)
• end.pile — End data (only if present)

Notes & Limits

• Whole-world in memory: optimized for small worlds (e.g., lobbies, minigames, Skyblock-style)
• Empty sections are extremely compact and compress well
• Entities/scheduled ticks scale with actual usage
• If you expect very large worlds, consider a chunk-addressable backend instead

Acknowledgments

This work is based on hollow-cube/go-polar.

Documentation

Index

• Constants
• type CompressionLevel
• type Provider
  • func New(dir string) (*Provider, error)
  • func NewReadOnly(dir string) (*Provider, error)
  • func NewReadOnlyWithCompression(dir string, compressionLevel CompressionLevel) (*Provider, error)
  • func NewWithCompression(dir string, compressionLevel CompressionLevel) (*Provider, error)
  • func (p *Provider) ChunkCount() int
  • func (p *Provider) Close() error
  • func (p *Provider) DimensionChunkCount(dim world.Dimension) int
  • func (p *Provider) DisableBackgroundSaves()
  • func (p *Provider) EnableBackgroundSaves()
  • func (p *Provider) IsDirty() bool
  • func (p *Provider) IsReadOnly() bool
  • func (p *Provider) LoadColumn(pos world.ChunkPos, dim world.Dimension) (*chunk.Column, error)
  • func (p *Provider) LoadPlayerSpawnPosition(id uuid.UUID) (cube.Pos, bool, error)
  • func (p *Provider) Save() error
  • func (p *Provider) SaveAsync()
  • func (p *Provider) SavePlayerSpawnPosition(id uuid.UUID, pos cube.Pos) error
  • func (p *Provider) SaveSettings(s *world.Settings)
  • func (p *Provider) SetCompressionLevel(level CompressionLevel)
  • func (p *Provider) SetStreamingSaves(enabled bool)
  • func (p *Provider) Settings() *world.Settings
  • func (p *Provider) StoreColumn(pos world.ChunkPos, dim world.Dimension, col *chunk.Column) error
• type Settings

Constants

const (
	// CompressionLevelNone disables compression.
	CompressionLevelNone = format.CompressionLevelNone
	// CompressionLevelFast uses fast compression (level 1).
	CompressionLevelFast = format.CompressionLevelFast
	// CompressionLevelDefault uses default compression (level 3).
	CompressionLevelDefault = format.CompressionLevelDefault
	// CompressionLevelBest uses best compression (level 9).
	CompressionLevelBest = format.CompressionLevelBest
)

Types

type CompressionLevel

type CompressionLevel = format.CompressionLevel

CompressionLevel represents the compression level for saving worlds.

type Provider

type Provider struct {
	// contains filtered or unexported fields
}

Provider implements world.Provider for the Pile world format. Pile is a single-file world format designed for small worlds. Note: Pile loads the entire world into memory, so it's only suitable for small worlds.

func New

func New(dir string) (*Provider, error)

New creates a new Pile provider in the given directory. If no world files exist, new ones will be created on first save.

func NewReadOnly

func NewReadOnly(dir string) (*Provider, error)

NewReadOnly creates a new read-only Pile provider in the given directory. All modification operations (StoreColumn, SaveSettings, SavePlayerSpawnPosition) will be silently ignored. The provider will not create any files if they don't exist.

func NewReadOnlyWithCompression

func NewReadOnlyWithCompression(dir string, compressionLevel CompressionLevel) (*Provider, error)

NewReadOnlyWithCompression creates a new read-only Pile provider with a specific compression level. The compression level is only used if the provider is later converted to read-write mode.

func NewWithCompression

func NewWithCompression(dir string, compressionLevel CompressionLevel) (*Provider, error)

NewWithCompression creates a new Pile provider with a specific compression level.

func (*Provider) ChunkCount

func (p *Provider) ChunkCount() int

ChunkCount returns the total number of chunks across all dimensions.

func (*Provider) Close

func (p *Provider) Close() error

Close saves all pending changes and closes the provider. Does nothing if the provider is read-only.

func (*Provider) DimensionChunkCount

func (p *Provider) DimensionChunkCount(dim world.Dimension) int

DimensionChunkCount returns the number of chunks in a specific dimension.

func (*Provider) DisableBackgroundSaves

func (p *Provider) DisableBackgroundSaves()

DisableBackgroundSaves stops the background save goroutine.

func (*Provider) EnableBackgroundSaves

func (p *Provider) EnableBackgroundSaves()

EnableBackgroundSaves starts a background goroutine that coalesces save requests and writes the world to disk asynchronously.

func (*Provider) IsDirty

func (p *Provider) IsDirty() bool

IsDirty returns whether the provider has unsaved changes.

func (*Provider) IsReadOnly

func (p *Provider) IsReadOnly() bool

IsReadOnly returns true if the provider is in read-only mode.

func (*Provider) LoadColumn

func (p *Provider) LoadColumn(pos world.ChunkPos, dim world.Dimension) (*chunk.Column, error)

LoadColumn loads a chunk column from the appropriate dimension.

func (*Provider) LoadPlayerSpawnPosition

func (p *Provider) LoadPlayerSpawnPosition(id uuid.UUID) (cube.Pos, bool, error)

LoadPlayerSpawnPosition loads a player's spawn position.

func (*Provider) Save

func (p *Provider) Save() error

Save forces a save of all worlds. Does nothing if the provider is read-only.

func (*Provider) SaveAsync

func (p *Provider) SaveAsync()

SaveAsync schedules a background save and returns immediately. If the background saver is not enabled, this is a no-op.

func (*Provider) SavePlayerSpawnPosition

func (p *Provider) SavePlayerSpawnPosition(id uuid.UUID, pos cube.Pos) error

SavePlayerSpawnPosition saves a player's spawn position. Silently ignores the operation if the provider is read-only.

func (*Provider) SaveSettings

func (p *Provider) SaveSettings(s *world.Settings)

SaveSettings saves the world settings. Silently ignores the operation if the provider is read-only.

func (*Provider) SetCompressionLevel

func (p *Provider) SetCompressionLevel(level CompressionLevel)

SetCompressionLevel sets the compression level for future saves.

func (*Provider) SetStreamingSaves

func (p *Provider) SetStreamingSaves(enabled bool)

SetStreamingSaves enables or disables streaming saves (chunk-by-chunk). When enabled, the provider streams chunks to disk instead of buffering the entire world.

func (*Provider) Settings

func (p *Provider) Settings() *world.Settings

Settings returns the world settings.

func (*Provider) StoreColumn

func (p *Provider) StoreColumn(pos world.ChunkPos, dim world.Dimension, col *chunk.Column) error

StoreColumn stores a chunk column to the appropriate dimension. Silently ignores the operation if the provider is read-only.

type Settings

type Settings struct {
	Name            string
	Spawn           cube.Pos
	Time            int64
	TimeCycle       bool
	RainTime        int64
	Raining         bool
	ThunderTime     int64
	Thundering      bool
	WeatherCycle    bool
	CurrentTick     int64
	DefaultGameMode int32
	Difficulty      int32
}

Settings is an internal representation of world settings for serialization.