# world-gen

**Repository Path**: sweetiron/world-gen

## Basic Information

- **Project Name**: world-gen
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-08-23
- **Last Updated**: 2025-08-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Dynamic World Generation Library

A highly configurable, deterministic 2D world generation library for Go, focused on seamless chunk-based terrain generation with difficulty scaling and border consistency.

## Features

- **Deterministic Generation**: Same seed + coordinates = identical output
- **Chunk-based Architecture**: 32×32 tile chunks for infinite worlds
- **Difficulty Scaling**: Adjust terrain danger levels (0.0-1.0)
- **Seamless Transitions**: Similarity coefficient controls border consistency
- **Minimal Dependencies**: Pure Go with Perlin noise support
- **Thread-safe**: Safe for concurrent chunk generation

## Installation

```bash
go get gitee.com/sweetiron/world-gen
```

## Quick Start

```go
package main

import (
	"fmt"
	"log"
	
	"gitee.com/sweetiron/world-gen"
)

func main() {
	// Initialize generator with seed
	seed := int64(42)
	generator := worldgen.NewNoiseGenerator(seed)
	
	// Generate a chunk
	coord := worldgen.ChunkCoord{X: 0, Y: 0}
	difficulty := 0.7  // Medium-hard difficulty
	similarity := 0.8  // High border consistency
	
	chunk, err := generator.GenerateChunk(seed, coord, difficulty, similarity, nil)
	if err != nil {
		log.Fatal(err)
	}
	
	// Print first few tiles
	for y := 0; y < 5; y++ {
		for x := 0; x < 5; x++ {
			fmt.Printf("%s ", worldgen.TileTypeString(chunk[y][x]))
		}
		fmt.Println()
	}
}
```

## Core Concepts

### Chunk Coordinates

Chunks are identified by `ChunkCoord{X, Y}` coordinates. Each chunk contains 32×32 tiles.

### Tile Types

- `TileTypeEmpty` - Empty space
- `TileTypeGrass` - Grassy plains
- `TileTypeWater` - Water bodies
- `TileTypeForest` - Dense forests
- `TileTypeMountain` - Mountainous terrain
- `TileTypeDesert` - Sandy deserts
- `TileTypeLava` - Dangerous lava

### Parameters

- **Seed** (`int64`): Ensures reproducible randomness
- **Difficulty** (`float64` 0.0-1.0): Controls terrain danger
  - 0.0: Safe (grass, forest, water)
  - 1.0: Dangerous (lava, mountains, desert)
- **Similarity** (`float64` 0.0-1.0): Border consistency with neighbors
  - 0.0: No blending
  - 1.0: Perfect seamless transitions

## Advanced Usage

### With Neighbor Blending

```go
// Create chunk cache
chunkCache := make(map[worldgen.ChunkCoord]worldgen.ChunkData)

// Function to query neighbors
getNeighbor := func(coord worldgen.ChunkCoord) (worldgen.ChunkData, error) {
	if data, exists := chunkCache[coord]; exists {
		return data, nil
	}
	return nil, nil
}

// Generate chunk with neighbors
coord := worldgen.ChunkCoord{X: 1, Y: 1}
neighbors := make(map[worldgen.ChunkCoord]worldgen.ChunkData)

// Query adjacent chunks
for _, offset := range []worldgen.ChunkCoord{{-1, 0}, {1, 0}, {0, -1}, {0, 1}} {
	neighborCoord := worldgen.ChunkCoord{X: coord.X + offset.X, Y: coord.Y + offset.Y}
	if neighborData, err := getNeighbor(neighborCoord); err == nil && neighborData != nil {
		neighbors[neighborCoord] = neighborData
	}
}

chunk, err := generator.GenerateChunk(seed, coord, difficulty, similarity, neighbors)
```

### Custom Generators

Implement the `Generator` interface:

```go
type CustomGenerator struct {
	seed int64
}

func (g *CustomGenerator) GenerateChunk(seed int64, coord worldgen.ChunkCoord, 
	difficulty, similarity float64, neighbors map[worldgen.ChunkCoord]worldgen.ChunkData) (worldgen.ChunkData, error) {
	// Your custom generation logic
}
```

## Examples

Check the `example/` directory for:
- Basic generation demo
- Difficulty scaling examples
- Similarity blending demonstrations

## API Reference

### Types

- `ChunkCoord`: `{X, Y int}` - Chunk coordinates
- `TileType`: `int` - Terrain type enumeration
- `ChunkData`: `[][]TileType` - 32×32 tile data
- `Generator`: Core generation interface
- `NeighborProvider`: `func(ChunkCoord) (ChunkData, error)` - Neighbor query function

### Constants

- `ChunkSize = 32` - Chunk dimensions
- `DefaultDifficulty = 0.5` - Medium difficulty
- `DefaultSimilarity = 0.8` - High similarity

### Functions

- `NewNoiseGenerator(seed int64) Generator` - Create noise-based generator
- `TileTypeString(TileType) string` - Get human-readable tile name

## Performance

- Single chunk generation: ~100μs (typical)
- Memory efficient: ~4KB per chunk (32×32 × 4 bytes)
- Thread-safe for concurrent generation

## Contributing

1. Follow Go coding standards
2. Add comprehensive tests
3. Maintain deterministic behavior
4. Ensure thread safety
5. Document public APIs

## License

Mulan Permissive Software License v2 (MulanPSL-2.0) - see LICENSE file for details.