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 4×4 sub-chunk biome information.

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

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;                    // Random seed
    double temperature_scale = 0.005;          // Temperature noise scale
    double humidity_scale = 0.007;             // Humidity noise scale  
    double base_scale = 0.08;                  // Base terrain noise scale
};

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);

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 4×4 sub-chunk grid.

struct SubChunkPos {
    std::uint8_t sub_x; // 0-3
    std::uint8_t sub_y; // 0-3
};

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;
config.temperature_scale = 0.005;
config.humidity_scale = 0.007;
config.base_scale = 0.08;

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

// Access tiles
for (int chunk_y = 0; chunk_y < 4; ++chunk_y) {
    for (int chunk_x = 0; chunk_x < 4; ++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)
• A 4×4 chunk map contains 65,536 total tiles
• Sub-chunks provide efficient biome management (16×16 tile regions)
• Tiles are packed into 1 byte each for memory efficiency
• Generation uses Perlin noise for natural-looking terrain

Thread Safety

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