terraforge-core 1.6.0

A customizable Python tool for generating maps for games and simulations.

TerraForge v1.6.0 🗺️

Procedural Biome/Island, Town & Dungeon Map Generator using Simplex Noise

TerraForge is a versatile Python toolset for procedural map generation.

It includes tools for creating noise-based biome maps, procedural town layouts, and multi-level dungeon layouts...

---

🚀 Features

🌍 Biome Generator (TerraForge)

• Elevation, Moisture, and Temperature map generation
• Supports single and clustered multi-island generation
• Falloff support: Radial, Edge, or None
• Parameters for island spread, spacing, scale, and strength
• Biome mapping based on environmental conditions (supports both visual colors and logic-driven biome data)
• Outputs high-resolution PNG images
• JSON preset import/export for reuse in games

🏰 Dungeon Generator (DungeonForge)

• Multi-level dungeon generation (3D stack of floors)
• Procedural room placement and corridor carving
• Up/down stairs for vertical navigation
• Console-based movement demo included
• Optional PNG export per dungeon level
• Tile color customization for export
• JSON preset import/export

🏘️ Town Generator (TownForge)

• Procedural town generation
• Configurable building types and quantities
• Randomized building sizes and placement
• Overlap prevention with configurable spacing
• Configurable edge padding
• Randomized door placement
• Configurable door sides and inset spacing
• Building metadata access helpers
• Optional building label rendering
• PNG export support
• Deterministic generation using seeds

---

📦 Requirements

• noise
• numpy
• pillow

---

📦 Installation

You can install TerraForge using pip.

pip install terraforge-core

---

🧪 Demos

Biome Map Generator

Run the included demo script:

python demo.py

The generated maps will be saved as biome_map, elevation_map, moisture_map, temperature_map, (noise_type)_map.

Dungeon Map Generator

Run either the included dungeon_demo script or dungeon_demo1 script.

python dungeon_demo.py

Console based demo with movement.

python dungeon_demo1.py

Generates .pngs for each dungeon level.

Town Map Generator

from townforge import TownForge

generator = TownForge(
	map_size=300,
	image_size=None,
	seed=None,
	building_padding=4,
	map_edge_padding=5,
	door_inset=1,
	door_sides=("north", "south", "east", "west"),
)

town_map = generator.generate()

generator.export_town_map_image(
	output_dir=".",
	show_building_names=False,
)

This generates a procedural town map and exports it as a PNG image.

---

🚀 Usage - TerraForge (Biome Maps)

from terraforge import TerraForge

generator = TerraForge(map_size=300, image_size=(600, 600))

generator.generate(output_dir="maps")

🔁 Preset Workflow

generator.export_preset("world_preset.json")

generator.import_preset("world_preset.json")
generator.generate("maps")

🧩 Biome Schema (Presets)

Biomes are stored as a list of objects. Each biome requires:

• color (hex string)
• rules (dict of noise_type -> [min, max])

Optional (recommended for tools like TerraForge Studio):

• id (unique string per biome)
• name (display name)

Example biome:

{
  "id": "forest",
  "name": "Forest",
  "color": "#3E7C3C",
  "rules": {
    "elevation": [0.4, 0.6],
    "moisture": [0.5, 1.0]
  }
}

Notes:

• id is optional, but if provided it must be unique within the preset.
• Rule ranges must satisfy min <= max.

---

🧠 Accessing Biome Data

Each tile now stores full biome data instead of just a color.

biome = generator.get_biome(x, y)

print(biome["id"]) # logic (e.g., "forest", "ocean")
print(biome["name"]) # display name

To get the visual color of a tile:

color = generator.tile_color(x, y)

---

⚠️ Update (v1.4.0)

• biome_map now stores full biome dictionaries instead of hex color strings
• Use tile_color(x, y) to retrieve the visual color
• Use get_biome(x, y) for biome data and game logic
• PNG export behavior remains unchanged

---

🚀 Usage - DungeonForge (Dungeons)

from dungeonforge import DungeonForge

generator = DungeonForge()

dungeon_map = generator.generate()

🔁 Preset Workflow

generator.export_preset("dungeon_preset.json")

generator.import_preset("dungeon_preset.json")
generator.generate()

---

🚀 Usage - TownForge (Towns)

from townforge import TownForge

generator = TownForge()

town_map = generator.generate()

generator.export_town_map_image()

🧠 Accessing Building Data

building = generator.get_building_at(x, y)

print(building["name"])
print(building["type"])

You can also retrieve buildings by their door tile:

building = generator.get_building_by_door(x, y)

---

⚙️ Customization Options

Biome Generator

Edit the values in terraforge.py or the demo to control:

• map_size and image_size

• falloff type: "radial", "edge", or None

• num_islands, island_spread, min_island_spacing

• noise types (elevation, moisture, temperature)

• biome_thresholds for noise types (elevation, moisture, and temperature)

Dungeon Generator

• Map size (width, height)
• Number of levels (z_levels)
• Maximum rooms and room size constraints
• Tile symbols and export colors
• Specify which levels to export (levels=[0, 2])

Town Generator

• Map size
• Image size
• Building spacing/padding
• Map edge padding
• Door placement rules
• Door inset spacing
• Building types
• Building quantities
• Building sizes
• Building colors
• Ground color
• Door color
• Outline color
• Building label rendering
• Random seeds

---

Related Tools

TerraForge Studio

A GUI tool built on top of the TerraForge library that allows you to quickly generate multi-level dungeons for games, prototypes, and tabletop use.

---

Related Libraries

• CQCalendar: A lightweight, tick-based time/calendar/lunar cycle system for Python games and simulations.
• MoonTex: A procedural moon texture generator for Python that creates stylized, noise-based moon phase images.