instructed/tilemap/docs/api.md

Tilemap Library API Documentation

Overview

The tilemap library provides a flexible system for generating and managing tile-based terrain with biome support. The library consists of several main components:

• TileMap: The main map container holding chunks of tiles
• Chunk: 64x64 tile containers with biome information
• Tile: Individual map tiles with base and surface types
• TerrainGenerator: Procedural terrain generation system
• Biome System: Climate-based terrain variation

Core Classes

TileMap

The main container for the entire map, organized as an n×n grid of chunks.

class TileMap {
public:
    explicit TileMap(std::uint8_t size);
    
    std::uint8_t get_size() const;
    Chunk& get_chunk(std::uint8_t chunk_x, std::uint8_t chunk_y);
    const Chunk& get_chunk(std::uint8_t chunk_x, std::uint8_t chunk_y) const;
    
    Tile& get_tile(const TilePos& pos);
    const Tile& get_tile(const TilePos& pos) const;
    void set_tile(const TilePos& pos, const Tile& tile);
};

Constructor Parameters:

• size: Number of chunks per side (max 100), creating an n×n grid

Chunk

Each chunk contains 64×64 tiles and sub-chunk biome information.

struct Chunk {
    static constexpr uint8_t size = 64;           // Tiles per side
    static constexpr uint8_t subchunk_size = /* certain value */;  // Tiles per sub-chunk side
    static constexpr uint8_t subchunk_count = size / subchunk_size;  // Sub-chunks per side
    
    Tile tiles[size][size];                       // 64x64 tile grid
    BiomeType biome[subchunk_count][subchunk_count];
};

Tile

Individual map tiles with base terrain and surface features.

struct Tile {
    BaseTileType base : 4;      // Base terrain type
    SurfaceTileType surface : 4; // Surface features
};

Base Tile Types:

• Land: Standard ground terrain
• Mountain: Rocky elevated terrain
• Sand: Desert/beach terrain
• Water: Water bodies
• Ice: Frozen terrain

Surface Tile Types:

• Empty: No surface features
• Wood: Trees/vegetation
• Structure: Player-built structures

TilePos

Position structure for locating tiles within the map.

struct TilePos {
    uint8_t chunk_x;  // Chunk X coordinate
    uint8_t chunk_y;  // Chunk Y coordinate  
    uint8_t local_x;  // Tile X within chunk (0-63)
    uint8_t local_y;  // Tile Y within chunk (0-63)
};

Terrain Generation

GenerationConfig

Configuration parameters for terrain generation.

struct GenerationConfig {
    std::uint64_t seed = 0;                       // Seed for random generation
    
    // Temperature noise parameters
    double temperature_scale = 0.005;             // Scale for temperature noise
    int temperature_octaves = 3;                  // Number of octaves for temperature noise
    double temperature_persistence = 0.4;        // Persistence for temperature noise
    
    // Humidity noise parameters
    double humidity_scale = 0.005;               // Scale for humidity noise
    int humidity_octaves = 3;                    // Number of octaves for humidity noise
    double humidity_persistence = 0.4;          // Persistence for humidity noise
    
    // Base terrain noise parameters
    double base_scale = 0.08;                    // Scale for base terrain noise
    int base_octaves = 3;                        // Number of octaves for base terrain noise
    double base_persistence = 0.5;              // Persistence for base terrain noise
};

Parameters:

• seed: Random seed for all noise generators
• temperature_scale: Controls the scale/frequency of temperature variation across the map
• temperature_octaves: Number of noise octaves for temperature (more octaves = more detail)
• temperature_persistence: How much each octave contributes to temperature noise (0.0-1.0)
• humidity_scale: Controls the scale/frequency of humidity variation across the map
• humidity_octaves: Number of noise octaves for humidity
• humidity_persistence: How much each octave contributes to humidity noise (0.0-1.0)
• base_scale: Controls the scale/frequency of base terrain height variation
• base_octaves: Number of noise octaves for base terrain
• base_persistence: How much each octave contributes to base terrain noise (0.0-1.0)

TerrainGenerator

Main class for procedural terrain generation.

class TerrainGenerator {
public:
    explicit TerrainGenerator(const GenerationConfig& config);
    void generate_map(TileMap& tilemap);
};

Generation Function

Convenience function for map generation.

void map_generate(TileMap& tilemap, const GenerationConfig& config);

Noise System

PerlinNoise

Standard Perlin noise implementation for procedural generation.

class PerlinNoise {
public:
    explicit PerlinNoise(std::uint64_t seed = 0);
    double noise(double x, double y) const;
    double octave_noise(double x, double y, int octaves = 4, double persistence = 0.5) const;
};

UniformPerlinNoise

Advanced noise generator that provides uniform distribution mapping.

class UniformPerlinNoise {
public:
    explicit UniformPerlinNoise(std::uint64_t seed = 0);
    void calibrate(double scale, int octaves = 1, double persistence = 0.5, int sample_size = 10000);
    double uniform_noise(double x, double y) const;
    bool is_calibrated() const;
};

Key Features:

• Calibration: Samples noise distribution to build CDF
• Uniform Mapping: Maps raw Perlin values to uniform [0,1] distribution
• Balanced Output: Ensures even distribution across all value ranges
• Automatic Use: TerrainGenerator uses this internally for balanced terrain

Biome System

BiomeType

Available biome types based on temperature and humidity.

enum class BiomeType : std::uint8_t {
    SnowyPeeks,   // Cold & Dry
    SnowyPlains,  // Cold & Moderate  
    FrozenOcean,  // Cold & Wet
    Plains,       // Temperate & Dry
    Forest,       // Temperate & Moderate
    Ocean,        // Temperate & Wet
    Desert,       // Hot & Dry
    Savanna,      // Hot & Moderate
    LukeOcean,    // Hot & Wet
};

BiomeProperties

Properties that control terrain generation for each biome.

struct BiomeProperties {
    std::string_view name;      // Biome name
    double water_ratio;         // Water generation ratio
    double ice_ratio;           // Ice generation ratio  
    double sand_ratio;          // Sand generation ratio
    double land_ratio;          // Land generation ratio
    int base_octaves = 3;       // Noise octaves
    double base_persistence = 0.5; // Noise persistence
};

Biome Functions

const BiomeProperties& get_biome_properties(BiomeType biome);
BiomeType determine_biome(double temperature, double humidity);

SubChunkPos

Position within a chunk's sub-chunk grid.

struct SubChunkPos {
    std::uint8_t sub_x;
    std::uint8_t sub_y;
};

constexpr std::pair<std::uint8_t, std::uint8_t> subchunk_to_tile_start(
    const SubChunkPos& pos
);

Usage Examples

Basic Map Generation

#include "tilemap.h"
#include "generation.h"

// Create a 4x4 chunk map
istd::TileMap tilemap(4);

// Configure generation
istd::GenerationConfig config;
config.seed = 12345;

// Temperature noise settings
config.temperature_scale = 0.005;
config.temperature_octaves = 3;
config.temperature_persistence = 0.4;

// Humidity noise settings  
config.humidity_scale = 0.005;
config.humidity_octaves = 3;
config.humidity_persistence = 0.4;

// Base terrain noise settings
config.base_scale = 0.08;
config.base_octaves = 3;
config.base_persistence = 0.5;

// Generate terrain
istd::map_generate(tilemap, config);

// Access tiles
for (int chunk_y = 0; chunk_y < Chunk::subchunk_count; ++chunk_y) {
    for (int chunk_x = 0; chunk_x < Chunk::subchunk_count; ++chunk_x) {
        const auto& chunk = tilemap.get_chunk(chunk_x, chunk_y);
        // Process chunk tiles...
    }
}

Accessing Individual Tiles

// Using TilePos
istd::TilePos pos{0, 0, 32, 32}; // Chunk (0,0), tile (32,32)
const auto& tile = tilemap.get_tile(pos);

// Direct chunk access
const auto& chunk = tilemap.get_chunk(0, 0);
const auto& tile2 = chunk.tiles[32][32];

Working with Biomes

// Get biome for a sub-chunk
const auto& chunk = tilemap.get_chunk(0, 0);
istd::BiomeType biome = chunk.biome[1][1]; // Sub-chunk (1,1)

// Get biome properties
const auto& props = istd::get_biome_properties(biome);
std::cout << "Biome: " << props.name << std::endl;

Performance Notes

• Each chunk contains 4,096 tiles (64×64)
• Sub-chunks provide efficient biome management
• Tiles are packed into 1 byte each for memory efficiency
• Generation uses Perlin noise with uniform distribution mapping for balanced terrain
• Noise calibration is performed once during generator construction

Noise Distribution

The library uses an advanced noise system that addresses the non-uniform distribution of Perlin noise:

Problem with Raw Perlin Noise

Raw Perlin noise follows a bell-curve distribution, with most values concentrated around 0.5. This leads to unbalanced terrain generation where certain tile types (like Land) dominate the map.

Solution: Uniform Distribution Mapping

The UniformPerlinNoise class:

1. Samples the noise distribution during calibration
2. Builds a CDF (Cumulative Distribution Function) from the samples
3. Maps raw noise values to uniform [0,1] distribution using quantiles
4. Ensures balanced terrain type distribution according to biome properties

Usage in Terrain Generation

// The terrain generator automatically uses uniform noise
TerrainGenerator generator(config);
generator.generate_map(tilemap);  // Uses calibrated uniform noise internally

Thread Safety

The library is not inherently thread-safe. External synchronization is required for concurrent access to TileMap objects.