Floom

World building platform for Godot 4.x — procedural generation, content management, and gameplay validation in one monorepo.

---

What Is Floom?

Floom is a world builder. Not a room generator, not a dungeon generator — a world builder. It chisels masterpieces from empty space, ring by ring, collapsing chaos into coherent, living worlds.

Three standalone modules work independently or together:

Module	Purpose
FofLoom	Pure C# graph grammar engine — transforms abstract topology graphs into spatial layouts and 3D geometry via a 4-ring concentric collapse pipeline
Floom.ContentStore	Content catalogue and asset management — SQLite-based asset database with 10,836 assets, biome profiles, and PCG metadata queries
Floom.Validation	Monte Carlo simulation engine — agent-based balance testing, economy validation, and combat encounter tuning

Each module is standalone. Use FofLoom on its own for world generation. Add ContentStore for content-aware generation. Add Validation for automated balance testing. Or use all three together for the full pipeline.

Primary target: Godot 4.x with full .NET 10 integration via GDExtension. The generation pipeline is engine-agnostic — only the adapter layer is engine-specific.

---

Core Innovation

7 co-dependent graphs generated in a unified pipeline with cross-graph adaptation:

Spatial Topology → Physical Geometry → Encounters → Loot → Quests → Factions → Narrative

No other PCG tool generates all seven layers simultaneously, each aware of the others.

Concentric Collapse

Every step is a constraint collapse. Start with maximum entropy (all possible worlds) and chisel inward, ring by ring, until one specific world remains:

Ring 0: GRID         — "Where is the world?"      Establish bounds, subdivide into cells.
Ring 1: LAND         — "What is the ground?"       Biomes, terrain, water, vegetation.
Ring 2: CIVILIZATION — "What's built here?"         Zones, structures, interiors, paths.
Ring 3: PURPOSE      — "What happens here?"        Encounters, quests, narrative.
Ring 4: POLISH       — "What does it feel like?"   Props, lighting, atmosphere.

Each ring reads all outer rings (already locked), collapses its own decisions, and locks. No ring adds chaos — each only narrows. One grammar drives everything.

---

Quick Start

Prerequisites

• .NET 10 SDK
• Git

Build

git clone https://github.com/buildepicshit/Floom.git
cd Floom
dotnet build

Test

dotnet test --settings tests/test.runsettings

5,298 tests. 0 failures. 0 warnings. All with per-test timeouts.

Your First Grammar

Create a .floom file:

world "MyWorld" {
    rule start @ring(0) {
        space {
            add room(type="hub", size="large")
            add room(type="corridor", count=3)
            connect hub to corridor
        }
    }

    rule paint_biomes @ring(1) {
        space {
            paint biome("forest", weight=0.6)
            paint biome("volcanic", weight=0.4)
        }
    }
}

Generate:

dotnet run --project src/FofLoom.Cli -- generate --grammar my_world.floom --seed 42

---

Architecture

Floom implements a strict 5-layer pipeline:

Layer 1: Rule Authoring     — .floom DSL → parsed grammar rules
Layer 2: Graph Rewriting    — VF2 pattern matching → graph transformations
Layer 3: Spatial Embedding  — Force-directed layout → 2D/3D positioning
Layer 4: Geometric Realization — Shape grammar → meshes, corridors, props
Layer 5: Engine Adapter     — Godot, Unity, Unreal, or raw mesh export

Layer boundaries are strict: Layer 2 does not know about Layer 4. The generation pipeline is deterministic — same seed always produces the same output.

Key Properties

• Engine-agnostic core — No Godot, Unity, or Unreal references in the generation engine
• Immutable-first — Graph transformations produce new graphs, never mutate
• Deterministic — Same seed = same output, always
• Event-sourced — Every transformation logged for replay, animation, debugging, and forking
• Strategy pattern — Major algorithms are pluggable (rewrite, spatial, geometry strategies)

---

Project Structure

src/
├── FofLoom.Core/          Graph model, VF2 pattern matching, event sourcing
├── FofLoom.Spatial/        Force-directed layout, Voronoi, terrain, water
├── FofLoom.Geometry/       Room extrusion, corridors, WFC solver, 3D export
├── FofLoom.Dsl/            .floom parser, ring pipeline, verb handlers
├── FofLoom.Analysis/       Grammar induction, MCTS validation, extraction
├── FofLoom.Cli/            CLI (generate, extract, induce, explore, verify)
├── FofLoom.Analyzers/      Roslyn diagnostic analyzer (FL0001)
├── Floom.Godot/            Godot 4.x adapter (Terrain3D, meshes, lights)
├── Floom.ContentStore/     SQLite asset database, biome profiles, queries
├── Floom.Validation.Core/  Simulation core, statistics, entropy, batch runner
└── Floom.Validation.Agents/ Agent profiles, archetypes, utility AI strategies

tests/                      11 test projects, 5,298 tests
samples/                    Example grammars, Godot demo project
docs/                       Architecture, guides, research, roadmap

---

Documentation

Document	Description
Overview	What Floom is and how it works
Architecture	Layer-by-layer system architecture
How-To Guide	Practical guide for grammar authors, level designers, and engine integrators
API Reference	Public API documentation
Pipeline Tunables	Configuration reference for generation parameters
Roadmap	Current priorities and future plans
Layperson's Guide	Non-technical introduction

---

Contributing

We welcome contributions. Please read the Contributing Guide before submitting a PR.

Key requirements:

• 0 warnings, 0 test failures
• All tests have per-test timeouts
• Conventional commits (feat:, fix:, refactor:, docs:, test:)
• Engine-agnostic core — no engine imports in FofLoom.* projects

See the Code of Conduct for community standards.

---

Security

To report a vulnerability, see SECURITY.md. Do not open a public issue for security concerns.

---

License

MIT — Copyright (c) 2026 BuildEpicShit

---

Built by BES Studios