spatial

Spatial Module

The spatial module provides 2D spatial positioning and movement capabilities for the RPG Toolkit. It supports multiple grid systems, entity placement, movement tracking, and event-driven spatial queries.

Table of Contents

• Overview
• Key Concepts
• Quick Start
• Grid Systems
• Room Management
• Boundary Crossings
• Multi-Room Orchestration
• Entity Placement
• Event System Integration
• Query System
• API Reference
• Examples
• Testing

Overview

The spatial module is designed to handle 2D spatial positioning for tabletop RPGs and provides:

• Multiple Grid Systems: Square, offset-coordinate hex, axial-coordinate hex, and continuous gridless systems
• Entity Management: Place, move, and track entities in spatial environments
• Multi-Room Orchestration: Connect and manage multiple rooms with typed connections
• Event Integration: Automatic event publishing for spatial changes
• Query System: Efficient spatial queries for game mechanics
• Line of Sight: Calculate visibility and obstacles
• Boundary Crossings: Optional undirected barriers between adjacent cells
• Distance Calculation: Grid-appropriate distance calculations
• Layout Patterns: Common spatial arrangements (towers, dungeons, towns)

Key Concepts

Position

A Position represents a 2D coordinate in space:

type Position struct {
    X float64 `json:"x"`
    Y float64 `json:"y"`
}

Grid

The Grid interface defines how spatial calculations work:

• Square Grid: Uses Chebyshev distance
• HexGrid: Uses bounded, non-negative offset column/row coordinates with pointy-top or flat-top orientation
• AxialHexGrid: Uses origin-centered axial Q/R coordinates
• Gridless: Uses Euclidean distance on continuous positions

Room

A Room is a spatial container that implements core.Entity and manages:

• Entity placement and movement
• Grid-based spatial calculations
• Event publishing for changes
• Line of sight and range queries

Placeable

Entities that can be placed in rooms should implement the Placeable interface:

type Placeable interface {
    core.Entity
    GetSize() int
    BlocksMovement() bool
    BlocksLineOfSight() bool
}

Boundary Crossings

Room remains occupancy-focused. BasicRoom additionally implements the optional BoundaryAwareRoom capability for a barrier between two adjacent, in-grid positions. A boundary is normalized as an undirected pair when it is registered, so both directions share one record. It never occupies either endpoint. It applies to discrete square and hex grids; gridless rooms have no cell-pair crossing model and reject boundary registration. With no registered boundaries, BasicRoom retains its legacy movement, movement-query, and entity line-of-sight behavior without constructing or scanning a boundary-specific ray.

boundaryRoom := room // *spatial.BasicRoom
err := boundaryRoom.RegisterBoundary(spatial.Boundary{
    From:              spatial.Position{X: 4, Y: 5},
    To:                spatial.Position{X: 5, Y: 5},
    BlocksMovement:    true,
    BlocksLineOfSight: true,
})

// Movement and LoS both reject the crossing. Placement at either cell stays valid.
err = boundaryRoom.MoveEntity("hero-1", spatial.Position{X: 5, Y: 5})
blocked := boundaryRoom.IsLineOfSightBlocked(
    spatial.Position{X: 4, Y: 5},
    spatial.Position{X: 5, Y: 5},
)

// Re-register to change flags (for example, an opened door), or remove it.
err = boundaryRoom.RegisterBoundary(spatial.Boundary{
    From: spatial.Position{X: 4, Y: 5},
    To:   spatial.Position{X: 5, Y: 5},
})
err = boundaryRoom.RemoveBoundary(
    spatial.Position{X: 4, Y: 5},
    spatial.Position{X: 5, Y: 5},
)

Boundaries are transient spatial infrastructure, not persistence or content ownership. A higher-level dungeon/encounter owns authored records and registers its current crossings when rebuilding a room. Boundary endpoints must be finite integer cell coordinates; fractional and non-finite values are rejected before a pair is normalized.

Multi-cell MoveEntity calls and movement queries retain direct-move semantics: they follow the grid-provided GetLineOfSight ray, reject any blocked consecutive crossing, and do not find a detour. Boundary LoS checks use one lexicographically ordered endpoint ray so a boundary has the same result in either direction even when square Bresenham chooses different directional rays. Entity and boundary blockers use that same canonical ray for each evaluated sight lane.

For hex A*, SimplePathFinder.FindPathWithTraversal accepts a TraversalPredicate so callers can reject a crossing without treating either endpoint as a blocked cell. It also requires an explicit TraversalSearchLimit; MaxSteps bounds both returned path length and search cost, making a sealed-but-unblocked goal terminate on the unbounded hex plane. Choose a limit above the direct distance by the detour budget appropriate for the map. An empty result means either no route exists or no route fits that budget.

path := finder.FindPathWithTraversal(
    start,
    goal,
    blockedCells,
    canTraverse,
    spatial.TraversalSearchLimit{MaxSteps: 64},
)

Quick Start

1. Basic Setup

package main

import (
    "github.com/KirkDiggler/rpg-toolkit/core"
    "github.com/KirkDiggler/rpg-toolkit/events"
    "github.com/KirkDiggler/rpg-toolkit/tools/spatial"
)

func main() {
    // Create event bus
    eventBus := events.NewBus()
    
    // Create a 20x20 square grid
    grid := spatial.NewSquareGrid(spatial.SquareGridConfig{
        Width:  20,
        Height: 20,
    })
    
    // Create a room
    room := spatial.NewBasicRoom(spatial.BasicRoomConfig{
        ID:       "dungeon-room-1",
        Type:     "dungeon",
        Grid:     grid,
        EventBus: eventBus,
    })
    
    // Setup query system
    queryHandler := spatial.NewSpatialQueryHandler()
    queryHandler.RegisterRoom(room)
    
    // Create query utilities
    queryUtils := spatial.NewQueryUtils(queryHandler)
}

2. Entity Placement

// Create an entity (must implement core.Entity)
type Character struct {
    id   string
    name string
}

func (c *Character) GetID() string   { return c.id }
func (c *Character) GetType() string { return "character" }

// Create and place entity
hero := &Character{id: "hero-1", name: "Aragorn"}
position := spatial.Position{X: 10, Y: 10}

err := room.PlaceEntity(hero, position)
if err != nil {
    log.Fatal(err)
}

3. Movement and Queries

// Move entity
newPosition := spatial.Position{X: 12, Y: 10}
err := room.MoveEntity("hero-1", newPosition)

// Query entities in range
entities := room.GetEntitiesInRange(position, 5.0)

// Check line of sight
losPositions := room.GetLineOfSight(position, newPosition)
blocked := room.IsLineOfSightBlocked(position, newPosition)

Grid Systems

Square Grid

SquareGrid uses Chebyshev distance, so diagonal and orthogonal neighbors are both one unit apart.

grid := spatial.NewSquareGrid(spatial.SquareGridConfig{
    Width:  20,
    Height: 20,
})

Offset-Coordinate Hex Grid

HexGrid interprets Position.X/Y as bounded, non-negative offset column/row coordinates. It converts those values to cube coordinates internally and honors the configured pointy-top or flat-top orientation.

grid := spatial.NewHexGrid(spatial.HexGridConfig{
    Width:       15,
    Height:      15,
    Orientation: spatial.HexOrientationPointyTop,
})

Axial-Coordinate Hex Grid

AxialHexGrid interprets Position.X/Y directly as axial Q/R coordinates. Its bounds are centered on the origin, so negative coordinates can be valid. It has no orientation setting because axial coordinates already describe the hex axes.

grid := spatial.NewAxialHexGrid(spatial.AxialHexGridConfig{
    SpanWidth:  30,
    SpanHeight: 30,
})

These two hex implementations are intentionally distinct. A Position{X: 5, Y: 5} means offset column 5/row 5 to HexGrid, but axial Q=5/R=5 to AxialHexGrid; callers must select the implementation matching their stored coordinate contract.

Gridless

GridlessRoom uses Euclidean distance and allows fractional positioning.

grid := spatial.NewGridlessRoom(spatial.GridlessConfig{
    Width:  100.0,
    Height: 100.0,
})

Room Management

Creating Rooms

room := spatial.NewBasicRoom(spatial.BasicRoomConfig{
    ID:       "unique-room-id",
    Type:     "dungeon",  // or "outdoors", "tavern", etc.
    Grid:     grid,
    EventBus: eventBus,
})

Room Operations

// Place entity
err := room.PlaceEntity(entity, position)

// Move entity
err := room.MoveEntity(entityID, newPosition)

// Remove entity
err := room.RemoveEntity(entityID)

// Check if position is occupied
occupied := room.IsPositionOccupied(position)

// Get all entities at position
entities := room.GetEntitiesAt(position)

// Get entity position
pos, exists := room.GetEntityPosition(entityID)

Multi-Room Orchestration

The spatial module includes a powerful orchestration system for managing multiple connected rooms, enabling complex multi-room environments like dungeons, towns, towers, and more.

Key Concepts

RoomOrchestrator

A RoomOrchestrator manages multiple rooms and their connections:

• Room Management: Add, remove, and track multiple rooms
• Connection System: Define how rooms link together
• Entity Tracking: Track entities across all managed rooms
• Layout Patterns: Organize rooms using common spatial arrangements
• Event Integration: Publish events for all orchestration changes

Connection Types

The orchestrator supports different connection types for various scenarios:

// Connection types
spatial.ConnectionTypeDoor     // Standard doorway
spatial.ConnectionTypeStairs   // Vertical connections (floors)
spatial.ConnectionTypePassage  // Open corridors/hallways
spatial.ConnectionTypePortal   // Magical transport
spatial.ConnectionTypeBridge   // Spanning gaps/obstacles
spatial.ConnectionTypeTunnel   // Underground passages

Layout Patterns

Common spatial arrangements for multiple rooms:

// Layout types
spatial.LayoutTypeTower      // Vertical stacking (floors)
spatial.LayoutTypeBranching  // Hub and spoke pattern
spatial.LayoutTypeGrid       // 2D grid arrangement
spatial.LayoutTypeOrganic    // Irregular connections

Standalone rooms and managed rooms

A BasicRoom remains a valid standalone spatial container: call its PlaceEntity, MoveEntity, and RemoveEntity methods directly. Once rooms participate in a multi-room field, entity membership mutation uses the orchestrator's additive ManagedRoomMutator seam instead:

placed, err := orchestrator.PlaceEntity(&spatial.PlaceEntityInput{
    RoomID: "entrance-hall",
    Entity: hero,
    Position: spatial.Position{X: 10, Y: 10},
})

moved, err := orchestrator.MoveEntity(&spatial.MoveEntityInput{
    RoomID: "entrance-hall",
    EntityID: core.EntityID(hero.GetID()),
    To: spatial.Position{X: 12, Y: 10},
})

These verbs synchronously update both the room and the orchestrator's entity-to-room index and return typed spatial deltas as values. The event bus is an optional observer tail only: connecting no bus, connecting after rooms are added, or using different buses for rooms and the orchestrator does not change membership correctness or outputs. Spatial events retain their existing topics and payloads for observers, but the orchestrator never subscribes to room notifications to learn its own results.

Go room interfaces are aliases, not ownership tokens. After AddRoom, retained room references can still bypass the managed seam, and the same room can be passed to more than one orchestrator. Both uses are unsupported because they can stale an index; #909 deliberately adds no callback or ownership-token machinery. Hosts serialize managed mutations. Concurrent read queries remain safe, but re-entrant managed mutation from a synchronous event observer is not a supported contract.

A cross-room transition has two explicit steps because a connection does not choose a physical destination position:

transitioned, err := orchestrator.TransitionEntity(&spatial.TransitionEntityInput{
    EntityID: core.EntityID(hero.GetID()),
    FromRoom: "entrance-hall",
    ToRoom: "treasure-room",
    ConnectionID: "main-door",
})
// transitioned.Entity is physically removed and unindexed;
// transitioned.Transition.PlacementRequired is true.

placed, err := orchestrator.PlaceEntity(&spatial.PlaceEntityInput{
    RoomID: "treasure-room",
    Entity: transitioned.Entity,
    Position: spatial.Position{X: 1, Y: 7},
})

During the interval between those calls, GetEntityRoom returns false and CanMoveEntityBetweenRooms returns false. The legacy MoveEntityBetweenRooms(string, string, string, string) error signature is retained for source compatibility, but now has the same honest departure-only behavior and discards the explicit output. New compositions should use TransitionEntity.

Basic Orchestrator Usage

1. Creating an Orchestrator

// Create orchestrator
orchestrator := spatial.NewBasicRoomOrchestrator(spatial.BasicRoomOrchestratorConfig{
    ID:       "dungeon-orchestrator",
    Type:     "orchestrator",
    Layout:   spatial.LayoutTypeOrganic,
})

2. Adding Rooms

// Create rooms
room1 := spatial.NewBasicRoom(spatial.BasicRoomConfig{
    ID:       "entrance-hall",
    Type:     "chamber",
    Grid:     spatial.NewSquareGrid(spatial.SquareGridConfig{Width: 20, Height: 20}),
})

room2 := spatial.NewBasicRoom(spatial.BasicRoomConfig{
    ID:       "treasure-room",
    Type:     "chamber", 
    Grid:     spatial.NewSquareGrid(spatial.SquareGridConfig{Width: 15, Height: 15}),
})

// Add to orchestrator
err := orchestrator.AddRoom(room1)
err = orchestrator.AddRoom(room2)

3. Creating Connections

// Create a door connection
door := spatial.CreateDoorConnection(
    "main-door",
    "entrance-hall", // From room
    "treasure-room", // To room
    1.0,             // Traversal cost
)

// Add connection to orchestrator
err := orchestrator.AddConnection(door)

4. Transitioning Entities Between Rooms

Use the managed placement and transition verbs shown above. TransitionEntity returns the removed core.Entity, the departure delta, and the logical transition; the composition then chooses the destination position and calls managed PlaceEntity. No subscriber is required to recover either result.

Connection Helper Functions

The module provides helper functions for creating different connection types:

Door Connections

// Bidirectional door (most common)
door := spatial.CreateDoorConnection(
    "door-1", "room-a", "room-b", 1.0,
)
// Cost: 1.0, Reversible: true, Requirements: none

Stair Connections

// Stairs between floors
stairs := spatial.CreateStairsConnection(
    "stairs-up", "floor-1", "floor-2", 2.0,
    true, // goingUp - adds "can_climb" requirement
)
// Cost: 2.0, Reversible: true, Requirements: ["can_climb"] if going up

Portal Connections

// Magical portal
portal := spatial.CreatePortalConnection(
    "magic-portal", "material-plane", "feywild", 0.5,
    true, // bidirectional
)
// Cost: 0.5, Requirements: ["can_use_portals"]

Secret Passages

// Hidden passage
secret := spatial.CreateSecretPassageConnection(
    "secret-passage", "library", "hidden-chamber", 1.0,
    []string{"found_secret", "has_key"}, // Custom requirements
)
// Cost: 1.0, Reversible: true, Requirements: custom

Layout Patterns

Tower Layout (Vertical Stacking)

Perfect for multi-floor buildings:

// Create tower floors
floors := make([]spatial.Room, 5)
for i := 0; i < 5; i++ {
    floors[i] = spatial.NewBasicRoom(spatial.BasicRoomConfig{
        ID:   fmt.Sprintf("floor-%d", i+1),
        Type: "floor",
        Grid: spatial.NewSquareGrid(spatial.SquareGridConfig{Width: 20, Height: 20}),
        EventBus: eventBus,
    })
    orchestrator.AddRoom(floors[i])
}

// Connect floors with stairs
for i := 0; i < len(floors)-1; i++ {
    stairs := spatial.CreateStairsConnection(
        fmt.Sprintf("stairs-%d-%d", i+1, i+2),
        floors[i].GetID(),
        floors[i+1].GetID(),
        2.0,
        true, // going up
    )
    orchestrator.AddConnection(stairs)
}

// Set tower layout
orchestrator.SetLayout(spatial.LayoutTypeTower)

Branching Layout (Hub and Spoke)

Great for dungeons with a central hub:

// Create central hub
hub := spatial.NewBasicRoom(spatial.BasicRoomConfig{
    ID:   "central-hub",
    Type: "chamber",
    Grid: spatial.NewSquareGrid(spatial.SquareGridConfig{Width: 30, Height: 30}),
    EventBus: eventBus,
})
orchestrator.AddRoom(hub)

// Create branching rooms
branches := []string{"north-wing", "south-wing", "east-wing", "west-wing"}
positions := []spatial.Position{
    {X: 15, Y: 0},   // North exit
    {X: 15, Y: 29},  // South exit
    {X: 29, Y: 15},  // East exit
    {X: 0, Y: 15},   // West exit
}

for i, branchID := range branches {
    // Create branch room
    branch := spatial.NewBasicRoom(spatial.BasicRoomConfig{
        ID:   branchID,
        Type: "chamber",
        Grid: spatial.NewSquareGrid(spatial.SquareGridConfig{Width: 20, Height: 20}),
        EventBus: eventBus,
    })
    orchestrator.AddRoom(branch)
    
    // Connect to hub
    door := spatial.CreateDoorConnection(
        fmt.Sprintf("door-to-%s", branchID),
        "central-hub",
        branchID,
        1.0,
    )
    orchestrator.AddConnection(door)
}

orchestrator.SetLayout(spatial.LayoutTypeBranching)

Advanced Features

Pathfinding Between Rooms

// Find path between rooms
path, err := orchestrator.FindPath("entrance-hall", "treasure-room", hero)
if err != nil {
    log.Fatal(err)
}

// path contains room IDs in order: ["entrance-hall", "treasure-room"]
fmt.Printf("Path: %v\n", path)

Entity Tracking

// Track entity location
roomID, exists := orchestrator.GetEntityRoom("hero")
if exists {
    fmt.Printf("Hero is in room: %s\n", roomID)
}

// Get all entities in orchestrator
allRooms := orchestrator.GetAllRooms()
for roomID, room := range allRooms {
    entities := room.GetAllEntities()
    fmt.Printf("Room %s has %d entities\n", roomID, len(entities))
}

Connection Management

// Get all connections for a room
connections := orchestrator.GetRoomConnections("entrance-hall")
for _, conn := range connections {
    fmt.Printf("Connection: %s (%s)\n", conn.GetID(), conn.GetConnectionType())
}

// Check if entity can move through connection
canMove := orchestrator.CanMoveEntityBetweenRooms("hero", "room-a", "room-b", "door-1")

Layout Selection

SetLayout stores one of the caller-selected LayoutType values and publishes LayoutChangedTopic for observers. The module does not calculate room positions or layout metrics.

Event System Integration

Orchestrator topics are optional observer notifications. Managed mutations return their results directly; events are not a hidden result channel. TransitionEntity continues to publish the active room-transition observation:

spatial.EntityRoomTransitionTopic.On(eventBus).Subscribe(
    context.Background(),
    func(ctx context.Context, event spatial.EntityRoomTransitionEvent) error {
        fmt.Printf("Entity %s left %s for %s\n", event.EntityID, event.FromRoom, event.ToRoom)
        return nil
    },
)

Complete Multi-Room Example

func CreateDungeonExample() {
    // Setup
    eventBus := events.NewEventBus()
    orchestrator := spatial.NewBasicRoomOrchestrator(spatial.BasicRoomOrchestratorConfig{
        ID:     "dungeon-orchestrator",
        Type:   "orchestrator",
        Layout: spatial.LayoutTypeBranching,
    })
    orchestrator.ConnectToEventBus(eventBus) // Optional observer publication.
    
    // Create rooms
    entrance := spatial.NewBasicRoom(spatial.BasicRoomConfig{
        ID:       "entrance",
        Type:     "chamber",
        Grid:     spatial.NewSquareGrid(spatial.SquareGridConfig{Width: 20, Height: 20}),
    })
    
    corridor := spatial.NewBasicRoom(spatial.BasicRoomConfig{
        ID:       "corridor",
        Type:     "hallway",
        Grid:     spatial.NewSquareGrid(spatial.SquareGridConfig{Width: 30, Height: 10}),
    })
    
    treasureRoom := spatial.NewBasicRoom(spatial.BasicRoomConfig{
        ID:       "treasure",
        Type:     "chamber",
        Grid:     spatial.NewSquareGrid(spatial.SquareGridConfig{Width: 15, Height: 15}),
    })
    entrance.ConnectToEventBus(eventBus) // Optional room-event publication.
    corridor.ConnectToEventBus(eventBus)
    treasureRoom.ConnectToEventBus(eventBus)

    // Add rooms to orchestrator
    orchestrator.AddRoom(entrance)
    orchestrator.AddRoom(corridor)
    orchestrator.AddRoom(treasureRoom)
    
    // Create connections
    door1 := spatial.CreateDoorConnection(
        "entrance-to-corridor", "entrance", "corridor", 1.0,
    )
    
    door2 := spatial.CreateDoorConnection(
        "corridor-to-treasure", "corridor", "treasure", 1.0,
    )
    
    orchestrator.AddConnection(door1)
    orchestrator.AddConnection(door2)
    
    // Place entities through the managed seam.
    hero := &Character{id: "hero", entityType: "character"}
    monster := &Character{id: "orc", entityType: "monster"}
    _, _ = orchestrator.PlaceEntity(&spatial.PlaceEntityInput{
        RoomID: "entrance", Entity: hero, Position: spatial.Position{X: 5, Y: 5},
    })
    _, _ = orchestrator.PlaceEntity(&spatial.PlaceEntityInput{
        RoomID: "treasure", Entity: monster, Position: spatial.Position{X: 10, Y: 10},
    })

    // Each abstract transition returns the entity for caller-chosen placement.
    toCorridor, _ := orchestrator.TransitionEntity(&spatial.TransitionEntityInput{
        EntityID: "hero", FromRoom: "entrance", ToRoom: "corridor",
        ConnectionID: "entrance-to-corridor",
    })
    _, _ = orchestrator.PlaceEntity(&spatial.PlaceEntityInput{
        RoomID: "corridor", Entity: toCorridor.Entity, Position: spatial.Position{X: 1, Y: 1},
    })
    toTreasure, _ := orchestrator.TransitionEntity(&spatial.TransitionEntityInput{
        EntityID: "hero", FromRoom: "corridor", ToRoom: "treasure",
        ConnectionID: "corridor-to-treasure",
    })
    _, _ = orchestrator.PlaceEntity(&spatial.PlaceEntityInput{
        RoomID: "treasure", Entity: toTreasure.Entity, Position: spatial.Position{X: 1, Y: 1},
    })

    // Hero is physically placed and indexed in the treasure room.
    heroRoom, _ := orchestrator.GetEntityRoom("hero")
    fmt.Printf("Hero is in: %s\n", heroRoom) // "treasure"
}

Entity Placement

Implementing Placeable

For entities that need spatial properties:

type Monster struct {
    id   string
    size int
    solid bool
}

func (m *Monster) GetID() string              { return m.id }
func (m *Monster) GetType() string            { return "monster" }
func (m *Monster) GetSize() int               { return m.size }
func (m *Monster) BlocksMovement() bool       { return m.solid }
func (m *Monster) BlocksLineOfSight() bool    { return m.solid }

Placement Rules

• Entities cannot be placed on positions that would conflict with blocking entities
• The same entity can be moved to different positions
• Position validity depends on the grid system
• Events are automatically published for placement changes

Event System Integration

Spatial notifications use typed topics. Room topics include EntityPlacedTopic, EntityMovedTopic, EntityRemovedTopic, and RoomCreatedTopic. Orchestrator topics include RoomAddedTopic, RoomRemovedTopic, ConnectionAddedTopic, ConnectionRemovedTopic, EntityRoomTransitionTopic, and LayoutChangedTopic.

spatial.EntityPlacedTopic.On(eventBus).Subscribe(
    context.Background(),
    func(ctx context.Context, event spatial.EntityPlacedEvent) error {
        fmt.Printf("Entity %s placed at %v in room %s\n", event.EntityID, event.Position, event.RoomID)
        return nil
    },
)

Queries are synchronous calls through SpatialQueryHandler; they do not publish notifications.

Query System

The spatial module provides two ways to perform spatial queries:

Direct Room Queries

// Get entities within range
entities := room.GetEntitiesInRange(center, radius)

// Get positions within range
positions := room.GetPositionsInRange(center, radius)

// Line of sight
losPositions := room.GetLineOfSight(from, to)
blocked := room.IsLineOfSightBlocked(from, to)

Query Handler

For queries routed across registered rooms, construct QueryUtils with the direct handler and provide any entity-type vocabulary at the call site:

queryUtils := spatial.NewQueryUtils(queryHandler)
filter := spatial.NewSimpleEntityFilter().
    WithEntityTypes("ally", "opponent").
    WithExcludeIDs("entity-1")
entities, err := queryUtils.QueryEntitiesInRange(ctx, center, radius, roomID, filter)

valid, path, distance, err := queryUtils.QueryMovement(ctx, entity, from, to, roomID)
positions, blocked, err := queryUtils.QueryLineOfSight(ctx, from, to, roomID)

API Reference

Core Interfaces

Grid Interface

type Grid interface {
    GetShape() GridShape
    IsValidPosition(pos Position) bool
    GetDimensions() Dimensions
    Distance(from, to Position) float64
    GetNeighbors(pos Position) []Position
    IsAdjacent(pos1, pos2 Position) bool
    GetLineOfSight(from, to Position) []Position
    GetPositionsInRange(center Position, radius float64) []Position
}

Distance Field

Field floods outward from one or more sources over Grid.GetNeighbors, Dijkstra by Cost, and answers with the distance and predecessor of every cell it reached. Reach is a field with a Limit, a path is PathTo on the same field, and a blast that spreads around corners is a field under a walls-only predicate. What a cell means is not spatial's: it reaches the field through Passable and Cost.

func Field(g Grid, in FieldInput) (FieldOutput, error)

type FieldInput struct {
    Sources  []Position                   // flood from all of these at once
    Passable func(from, to Position) bool // required; nil fails closed
    Cost     func(from, to Position) int  // nil means one per step
    Limit    int                          // stop past this distance; 0 = unbounded
}

type FieldOutput struct {
    Dist map[Position]int      // every reached cell, sources at 0
    Prev map[Position]Position // the cell each was entered from; absent for sources
}

// PathTo reads the field backwards: the path excludes the source and ends at goal.
func (f FieldOutput) PathTo(goal Position) ([]Position, bool)

Placed footprint geometry

PlacedCoverage rasterises a freely placed rectangular footprint over an explicit universe of axial cells. TraceFootprint tests a closed segment against the same rectangle without depending on a grid. Both use the caller's continuous plane and report geometry only: thresholds, movement, sight, cover, and whether a prop occupies room cells remain caller policy.

HexEmbedding.CellWidth, points, and box dimensions all use the caller's chosen unit; spatial has no notion of feet. Plane X runs east and Y runs south. Facing maps local +X to (cos(a), sin(a)), so positive 90 degrees points south. Box.D runs along local X, Box.W across local Y, and LocalOffset shifts the box centre in those local axes before rotation and translation by Origin.

type FootprintPlacement struct {
    Footprint   Footprint
    Origin      Point
    Facing      float64
    LocalOffset Point
}

type PlacedCoverageInput struct {
    Embedding HexEmbedding
    Placement FootprintPlacement
    Cells     []Position // exact finite integral axial cells to inspect
}

func PlacedCoverage(in PlacedCoverageInput) (CoverageOutput, error)

type FootprintTraceInput struct {
    Placement FootprintPlacement
    From, To  Point
}

type FootprintTraceOutput struct {
    Contact  bool    // meets the closed rectangle
    Interior bool    // positive-length portion lies strictly inside
    Enter    float64 // contact interval in [0,1]
    Leave    float64
}

func TraceFootprint(in FootprintTraceInput) (FootprintTraceOutput, error)

Coverage misses are absent from the output map; duplicates are idempotent. An empty candidate universe returns a non-nil empty map after validating the embedding and placement. Callers provide bounded candidate sets: the query does not infer floor, void, map membership, or nearest cells. Invalid or non-finite geometry, widths, endpoints, and fractional/non-finite cells return an error and never a partial coverage map.

For traces, edge overlap and a corner touch are contact but not interior. A stationary point inside or on the rectangle is contact with interval [0,0] and is not interior; a stationary point outside is a miss. Reversing a segment maps the interval to [1-Leave, 1-Enter].

emb := spatial.NewHexEmbedding(spatial.HexEmbeddingConfig{CellWidth: 5})
placement := spatial.FootprintPlacement{
    Footprint: spatial.Footprint{Box: &spatial.Box{W: 4, D: 10}},
    Origin: spatial.Point{X: 3.25, Y: -1.75},
    Facing: 37,
}
coverage, err := spatial.PlacedCoverage(spatial.PlacedCoverageInput{
    Embedding: emb,
    Placement: placement,
    Cells: []spatial.Position{{}, {X: 1}, {Y: -1}},
})
trace, err := spatial.TraceFootprint(spatial.FootprintTraceInput{
    Placement: placement,
    From: spatial.Point{X: -5},
    To: spatial.Point{X: 8},
})

Coverage remains the cell-anchored compatibility entry point. It converts the anchor cell through CellCentre, supplies a bounded candidate set from the grid, and delegates to PlacedCoverage. AnchorAtCentre centres the box on the cell; AnchorAtEdge puts its near edge one cell inradius along Facing. Existing spell thresholds remain above this API.

These queries do not make props occupy cells in BasicRoom, persist authored footprints, load meshes, or add scale, height, and polygon support.

Shared sight-lane evaluation

SightLanes exposes the same direct and progress-making-neighbour lane calculation used by BasicRoom, while callers supply obstruction facts. Along reports hard obstructions that cannot be bypassed and soft obstructions that an alternate lane may bypass; both block the lane on which they appear. At reports an opaque alternate origin. It is not a movement or standing query.

Each Along call receives one canonical Ray, oriented from From toward To. Treat the ray as read-only and do not retain it. The query retains no callbacks and takes no locks, so callers own a stable view for its duration. Missing collaborators and non-finite endpoints return the documented errors; any callback error is returned with a zero output rather than being interpreted as clear or blocked sight.

Continuous footprints compose without occupying a BasicRoom cell:

type footprintSight struct {
    emb       spatial.HexEmbedding
    placement spatial.FootprintPlacement
}

func (f footprintSight) Along(in spatial.SightLaneInput) (spatial.SightLaneOutput, error) {
    trace, err := spatial.TraceFootprint(spatial.FootprintTraceInput{
        Placement: f.placement,
        From:      f.emb.CellCentre(in.From),
        To:        f.emb.CellCentre(in.To),
    })
    return spatial.SightLaneOutput{SoftBlocked: trace.Interior}, err
}

func (f footprintSight) At(in spatial.SightCellInput) (spatial.SightCellOutput, error) {
    point := f.emb.CellCentre(in.At)
    trace, err := spatial.TraceFootprint(spatial.FootprintTraceInput{
        Placement: f.placement,
        From:      point,
        To:        point,
    })
    return spatial.SightCellOutput{Blocked: trace.Contact}, err
}

obstructions := footprintSight{
    emb: spatial.NewHexEmbedding(spatial.HexEmbeddingConfig{CellWidth: 5}),
    placement: spatial.FootprintPlacement{
        Footprint: spatial.Footprint{Box: &spatial.Box{W: 30, D: 0.2}},
    },
}
result, err := spatial.SightLanes(spatial.SightLanesInput{
    Grid:         spatial.NewAxialHexGrid(spatial.AxialHexGridConfig{SpanWidth: 9, SpanHeight: 9}),
    From:         spatial.Position{X: -2},
    To:           spatial.Position{X: 2},
    Obstructions: obstructions,
})

This example demonstrates geometry composition only; live prop ownership, standing thresholds, cover rules, and persistence remain caller policy. BasicRoom.IsLineOfSightBlocked delegates through an internal obstruction reader while holding its existing read lock, giving its callbacks a stable view.

Room Interface

type Room interface {
    core.Entity
    GetGrid() Grid
    PlaceEntity(entity core.Entity, pos Position) error
    MoveEntity(entityID string, newPos Position) error
    RemoveEntity(entityID string) error
    GetEntitiesAt(pos Position) []core.Entity
    GetEntityPosition(entityID string) (Position, bool)
    GetAllEntities() map[string]core.Entity
    GetEntitiesInRange(center Position, radius float64) []core.Entity
    IsPositionOccupied(pos Position) bool
    CanPlaceEntity(entity core.Entity, pos Position) bool
    GetPositionsInRange(center Position, radius float64) []Position
    GetLineOfSight(from, to Position) []Position
    IsLineOfSightBlocked(from, to Position) bool
}

RoomOrchestrator Interface

type RoomOrchestrator interface {
    core.Entity
    EventBusIntegration
    
    // Room management
    AddRoom(room Room) error
    RemoveRoom(roomID string) error
    GetRoom(roomID string) (Room, bool)
    GetAllRooms() map[string]Room
    
    // Connection management
    AddConnection(connection Connection) error
    RemoveConnection(connectionID string) error
    GetConnection(connectionID string) (Connection, bool)
    GetRoomConnections(roomID string) []Connection
    GetAllConnections() map[string]Connection
    
    // Entity movement
    MoveEntityBetweenRooms(entityID, fromRoom, toRoom, connectionID string) error
    CanMoveEntityBetweenRooms(entityID, fromRoom, toRoom, connectionID string) bool
    GetEntityRoom(entityID string) (string, bool)
    
    // Pathfinding
    FindPath(fromRoom, toRoom string, entity core.Entity) ([]string, error)
    
    // Layout management
    GetLayout() LayoutType
    SetLayout(layout LayoutType) error
}

Connection Interface

type Connection interface {
    core.Entity
    
    GetConnectionType() ConnectionType
    GetFromRoom() string
    GetToRoom() string
    GetFromPosition() Position
    GetToPosition() Position
    IsPassable(entity core.Entity) bool
    GetTraversalCost(entity core.Entity) float64
    IsReversible() bool
    GetRequirements() []string
}

Grid Constructors

// Square grid
func NewSquareGrid(config SquareGridConfig) *SquareGrid

// Hex grid
func NewHexGrid(config HexGridConfig) *HexGrid

// Gridless room
func NewGridlessRoom(config GridlessConfig) *GridlessRoom

Room Constructor

func NewBasicRoom(config BasicRoomConfig) *BasicRoom

Query System

// Query handler
func NewSpatialQueryHandler() *SpatialQueryHandler

// Query utilities
func NewQueryUtils(queryHandler *SpatialQueryHandler) *QueryUtils

Examples

Complete Combat Scenario

package main

import (
    "context"
    "fmt"
    "log"
    
    "github.com/KirkDiggler/rpg-toolkit/core"
    "github.com/KirkDiggler/rpg-toolkit/events"
    "github.com/KirkDiggler/rpg-toolkit/tools/spatial"
)

type Combatant struct {
    id        string
    name      string
    entityType string
    size      int
    blocking  bool
}

func (c *Combatant) GetID() string              { return c.id }
func (c *Combatant) GetType() string            { return c.entityType }
func (c *Combatant) GetSize() int               { return c.size }
func (c *Combatant) BlocksMovement() bool       { return c.blocking }
func (c *Combatant) BlocksLineOfSight() bool    { return c.blocking }

func main() {
    // Setup
    eventBus := events.NewBus()
    
    grid := spatial.NewSquareGrid(spatial.SquareGridConfig{
        Width:  20,
        Height: 20,
    })
    
    room := spatial.NewBasicRoom(spatial.BasicRoomConfig{
        ID:       "combat-room",
        Type:     "dungeon",
        Grid:     grid,
        EventBus: eventBus,
    })
    
    queryHandler := spatial.NewSpatialQueryHandler()
    queryHandler.RegisterRoom(room)
    
    queryUtils := spatial.NewQueryUtils(queryHandler)
    
    // Create combatants
    hero := &Combatant{
        id:        "hero",
        name:      "Hero",
        entityType: "character",
        size:      1,
        blocking:  true,
    }
    
    orc := &Combatant{
        id:        "orc",
        name:      "Orc",
        entityType: "monster",
        size:      1,
        blocking:  true,
    }
    
    goblin := &Combatant{
        id:        "goblin",
        name:      "Goblin",
        entityType: "monster",
        size:      1,
        blocking:  true,
    }
    
    // Place entities
    room.PlaceEntity(hero, spatial.Position{X: 5, Y: 5})
    room.PlaceEntity(orc, spatial.Position{X: 8, Y: 8})
    room.PlaceEntity(goblin, spatial.Position{X: 12, Y: 6})
    
    // Query nearby enemies
    ctx := context.Background()
    enemyFilter := spatial.NewSimpleEntityFilter().WithEntityTypes("monster")
    
    nearbyEnemies, err := queryUtils.QueryEntitiesInRange(
        ctx, 
        spatial.Position{X: 5, Y: 5}, // Hero's position
        10.0,                        // 10 unit range
        "combat-room",
        enemyFilter,
    )
    
    if err != nil {
        log.Fatal(err)
    }
    
    fmt.Printf("Enemies within 10 units of hero: %d\n", len(nearbyEnemies))
    
    // Check line of sight to orc
    losPositions, blocked, err := queryUtils.QueryLineOfSight(
        ctx,
        spatial.Position{X: 5, Y: 5},  // Hero
        spatial.Position{X: 8, Y: 8},  // Orc
        "combat-room",
    )
    
    if err != nil {
        log.Fatal(err)
    }
    
    fmt.Printf("Line of sight blocked: %v\n", blocked)
    fmt.Printf("LOS path length: %d\n", len(losPositions))
    
    // Validate movement
    valid, path, distance, err := queryUtils.QueryMovement(
        ctx,
        hero,
        spatial.Position{X: 5, Y: 5},  // From
        spatial.Position{X: 7, Y: 7},  // To
        "combat-room",
    )
    
    if err != nil {
        log.Fatal(err)
    }
    
    fmt.Printf("Movement valid: %v, distance: %.2f\n", valid, distance)
    fmt.Printf("Path length: %d\n", len(path))
    
    // Move hero if valid
    if valid {
        err = room.MoveEntity("hero", spatial.Position{X: 7, Y: 7})
        if err != nil {
            log.Fatal(err)
        }
        fmt.Println("Hero moved successfully!")
    }
}

Grid System Comparison

func compareGridSystems() {
    // Same positions for comparison
    from := spatial.Position{X: 2, Y: 2}
    to := spatial.Position{X: 6, Y: 6}
    
    // Square grid
    squareGrid := spatial.NewSquareGrid(spatial.SquareGridConfig{
        Width: 10, Height: 10,
    })
    
    // Hex grid
    hexGrid := spatial.NewHexGrid(spatial.HexGridConfig{
        Width: 10, Height: 10, PointyTop: true,
    })
    
    // Gridless
    gridlessRoom := spatial.NewGridlessRoom(spatial.GridlessConfig{
        Width: 10, Height: 10,
    })
    
    // Compare distances
    fmt.Printf("Distance from %v to %v:\n", from, to)
    fmt.Printf("Square Grid: %.2f\n", squareGrid.Distance(from, to))
    fmt.Printf("Hex Grid: %.2f\n", hexGrid.Distance(from, to))
    fmt.Printf("Gridless: %.2f\n", gridlessRoom.Distance(from, to))
    
    // Compare neighbors
    pos := spatial.Position{X: 5, Y: 5}
    fmt.Printf("\nNeighbors of %v:\n", pos)
    fmt.Printf("Square Grid: %d\n", len(squareGrid.GetNeighbors(pos)))
    fmt.Printf("Hex Grid: %d\n", len(hexGrid.GetNeighbors(pos)))
    fmt.Printf("Gridless: %d\n", len(gridlessRoom.GetNeighbors(pos)))
}

API Reference

Core Interfaces

Grid Interface

type Grid interface {
    GetShape() GridShape
    IsValidPosition(pos Position) bool
    GetDimensions() Dimensions
    Distance(from, to Position) float64
    GetNeighbors(pos Position) []Position
    IsAdjacent(pos1, pos2 Position) bool
    GetLineOfSight(from, to Position) []Position
    GetPositionsInRange(center Position, radius float64) []Position
}

Room Interface

type Room interface {
    core.Entity
    GetGrid() Grid
    PlaceEntity(entity core.Entity, pos Position) error
    MoveEntity(entityID string, newPos Position) error
    RemoveEntity(entityID string) error
    GetEntitiesAt(pos Position) []core.Entity
    GetEntityPosition(entityID string) (Position, bool)
    GetAllEntities() map[string]core.Entity
    GetEntitiesInRange(center Position, radius float64) []core.Entity
    IsPositionOccupied(pos Position) bool
    CanPlaceEntity(entity core.Entity, pos Position) bool
    GetPositionsInRange(center Position, radius float64) []Position
    GetLineOfSight(from, to Position) []Position
    IsLineOfSightBlocked(from, to Position) bool
}

RoomOrchestrator Interface

type RoomOrchestrator interface {
    core.Entity
    EventBusIntegration
    
    // Room management
    AddRoom(room Room) error
    RemoveRoom(roomID string) error
    GetRoom(roomID string) (Room, bool)
    GetAllRooms() map[string]Room
    
    // Connection management
    AddConnection(connection Connection) error
    RemoveConnection(connectionID string) error
    GetConnection(connectionID string) (Connection, bool)
    GetRoomConnections(roomID string) []Connection
    GetAllConnections() map[string]Connection
    
    // Entity movement
    MoveEntityBetweenRooms(entityID, fromRoom, toRoom, connectionID string) error
    CanMoveEntityBetweenRooms(entityID, fromRoom, toRoom, connectionID string) bool
    GetEntityRoom(entityID string) (string, bool)
    
    // Pathfinding
    FindPath(fromRoom, toRoom string, entity core.Entity) ([]string, error)
    
    // Layout management
    GetLayout() LayoutType
    SetLayout(layout LayoutType) error
}

Connection Interface

type Connection interface {
    core.Entity
    
    GetConnectionType() ConnectionType
    GetFromRoom() string
    GetToRoom() string
    GetFromPosition() Position
    GetToPosition() Position
    IsPassable(entity core.Entity) bool
    GetTraversalCost(entity core.Entity) float64
    IsReversible() bool
    GetRequirements() []string
}

Constructors

Grid Constructors

// Square grid
func NewSquareGrid(config SquareGridConfig) *SquareGrid

// Hex grid
func NewHexGrid(config HexGridConfig) *HexGrid

// Gridless room
func NewGridlessRoom(config GridlessConfig) *GridlessRoom

Room Constructor

func NewBasicRoom(config BasicRoomConfig) *BasicRoom

Orchestrator Constructor

func NewBasicRoomOrchestrator(config BasicRoomOrchestratorConfig) *BasicRoomOrchestrator

Connection Constructor

func NewBasicConnection(config BasicConnectionConfig) *BasicConnection

Connection Helper Functions

The module provides helper functions for creating common connection types:

// Door connection (bidirectional, cost 1.0)
func CreateDoorConnection(id, fromRoom, toRoom string, cost float64) *BasicConnection

// Stair connection (bidirectional, cost 2.0, may have climb requirement)
func CreateStairsConnection(id, fromRoom, toRoom string, cost float64, goingUp bool) *BasicConnection

// Secret passage (bidirectional, cost 1.0, requires discovery)
func CreateSecretPassageConnection(id, fromRoom, toRoom string, cost float64, requirements []string) *BasicConnection

// Portal connection (configurable direction, cost 0.5, requires portal use)
func CreatePortalConnection(id, fromRoom, toRoom string, cost float64, bidirectional bool) *BasicConnection

// Bridge connection (bidirectional, cost 1.0)
func CreateBridgeConnection(id, fromRoom, toRoom string, cost float64) *BasicConnection

// Tunnel connection (bidirectional, cost 1.5)
func CreateTunnelConnection(id, fromRoom, toRoom string, cost float64) *BasicConnection

Query System

// Query handler
func NewSpatialQueryHandler() *SpatialQueryHandler

// Query utilities
func NewQueryUtils(queryHandler *SpatialQueryHandler) *QueryUtils

Typed Event Topics

Room and orchestrator observations are exposed as typed topics:

spatial.EntityPlacedTopic
spatial.EntityMovedTopic
spatial.EntityRemovedTopic
spatial.RoomCreatedTopic
spatial.RoomAddedTopic
spatial.RoomRemovedTopic
spatial.ConnectionAddedTopic
spatial.ConnectionRemovedTopic
spatial.EntityRoomTransitionTopic
spatial.LayoutChangedTopic

Spatial queries use direct handler calls and have no event constants.

Types and Constants

Managed entity membership accepts core.EntityID. Spatial-specific identity remains available as RoomID, ConnectionID, and OrchestratorID.

Connection Types

const (
    ConnectionTypeDoor    ConnectionType = "door"
    ConnectionTypeStairs  ConnectionType = "stairs"
    ConnectionTypePassage ConnectionType = "passage"
    ConnectionTypePortal  ConnectionType = "portal"
    ConnectionTypeBridge  ConnectionType = "bridge"
    ConnectionTypeTunnel  ConnectionType = "tunnel"
)

Layout Types

const (
    LayoutTypeTower     LayoutType = "tower"
    LayoutTypeBranching LayoutType = "branching"
    LayoutTypeGrid      LayoutType = "grid"
    LayoutTypeOrganic   LayoutType = "organic"
)

Testing

The spatial module includes comprehensive tests. To run them:

go test ./...

Test Structure

• *_test.go - Unit tests for each grid system
• room_test.go - Room functionality tests
• query_handler_test.go - Query system tests
• examples_test.go - Integration examples and usage patterns

Mock Entities

For testing, use the provided mock entity pattern:

type MockEntity struct {
    id       string
    entityType string
    size     int
    blocksMovement bool
    blocksLOS  bool
}

func (m *MockEntity) GetID() string              { return m.id }
func (m *MockEntity) GetType() string            { return m.entityType }
func (m *MockEntity) GetSize() int               { return m.size }
func (m *MockEntity) BlocksMovement() bool       { return m.blocksMovement }
func (m *MockEntity) BlocksLineOfSight() bool    { return m.blocksLOS }

Advanced Usage Patterns

Error Handling and Validation

// Always check for errors when working with orchestrators
orchestrator := spatial.NewBasicRoomOrchestrator(config)

// Validate room addition
if err := orchestrator.AddRoom(room); err != nil {
    log.Printf("Failed to add room: %v", err)
    return err
}

// Validate connection requirements
if !orchestrator.CanMoveEntityBetweenRooms(entityID, fromRoom, toRoom, connectionID) {
    log.Printf("Entity %s cannot move through connection %s", entityID, connectionID)
    return errors.New("movement blocked")
}

// Safe entity movement with rollback
if err := orchestrator.MoveEntityBetweenRooms(entityID, fromRoom, toRoom, connectionID); err != nil {
    log.Printf("Movement failed: %v", err)
    // Handle failure (entity remains in original room)
}

Event-Driven Observer Logic

spatial.EntityRoomTransitionTopic.On(eventBus).Subscribe(
    context.Background(),
    func(ctx context.Context, event spatial.EntityRoomTransitionEvent) error {
        return observeRoomDeparture(event.EntityID, event.FromRoom, event.ToRoom)
    },
)

spatial.ConnectionAddedTopic.On(eventBus).Subscribe(
    context.Background(),
    func(ctx context.Context, event spatial.ConnectionAddedEvent) error {
        return updateMapConnection(event.ConnectionID, event.FromRoom, event.ToRoom)
    },
)

Dynamic Connection Management

// Create locked door that can be unlocked
door := spatial.CreateDoorConnection("treasure-door", "hallway", "treasure-room", 1.0)
door.SetPassable(false) // Initially locked
door.AddRequirement("has_key")
orchestrator.AddConnection(door)

// Unlock door when key is found
func unlockDoor(orchestrator spatial.RoomOrchestrator, connectionID string) error {
    if conn, exists := orchestrator.GetConnection(connectionID); exists {
        if basicConn, ok := conn.(*spatial.BasicConnection); ok {
            basicConn.SetPassable(true)
            basicConn.RemoveRequirement("has_key")
            return nil
        }
    }
    return errors.New("connection not found")
}

Performance Optimization

// For large orchestrators, consider batching operations
func addMultipleRooms(orchestrator spatial.RoomOrchestrator, rooms []spatial.Room) error {
    // Add rooms in batch to reduce event overhead
    for _, room := range rooms {
        if err := orchestrator.AddRoom(room); err != nil {
            return fmt.Errorf("failed to add room %s: %w", room.GetID(), err)
        }
    }
    return nil
}

// Use pathfinding sparingly for large orchestrators
func findOptimalPath(orchestrator spatial.RoomOrchestrator, entity core.Entity, fromRoom, toRoom string) ([]string, error) {
    // Cache paths for frequently used routes
    cacheKey := fmt.Sprintf("%s-%s-%s", entity.GetType(), fromRoom, toRoom)
    if cachedPath, exists := pathCache[cacheKey]; exists {
        return cachedPath, nil
    }
    
    path, err := orchestrator.FindPath(fromRoom, toRoom, entity)
    if err == nil {
        pathCache[cacheKey] = path
    }
    return path, err
}

Layout-Specific Patterns

// Tower layout - vertical progression
func createTowerDungeon(orchestrator spatial.RoomOrchestrator, floors int) {
    orchestrator.SetLayout(spatial.LayoutTypeTower)
    
    for i := 0; i < floors; i++ {
        // Create floor room
        floor := createFloorRoom(i)
        orchestrator.AddRoom(floor)
        
        // Connect to previous floor
        if i > 0 {
            stairs := spatial.CreateStairsConnection(
                fmt.Sprintf("stairs-%d", i),
                fmt.Sprintf("floor-%d", i-1),
                fmt.Sprintf("floor-%d", i),
                2.0,
                true, // going up
            )
            orchestrator.AddConnection(stairs)
        }
    }
}

// Branching layout - hub and spoke
func createBranchingDungeon(orchestrator spatial.RoomOrchestrator, hubRoom spatial.Room, branches []spatial.Room) {
    orchestrator.SetLayout(spatial.LayoutTypeBranching)
    orchestrator.AddRoom(hubRoom)
    
    for i, branch := range branches {
        orchestrator.AddRoom(branch)
        
        // Connect each branch to hub
        door := spatial.CreateDoorConnection(
            fmt.Sprintf("hub-to-branch-%d", i), hubRoom.GetID(), branch.GetID(), 1.0,
        )
        orchestrator.AddConnection(door)
    }
}

Testing Orchestrator Behavior

func TestOrchestratorBehavior(t *testing.T) {
    // Setup
    orchestrator := spatial.NewBasicRoomOrchestrator(spatial.BasicRoomOrchestratorConfig{
        ID: "test-orchestrator",
    })
    
    // Create test scenario
    room1 := createTestRoom("room1")
    room2 := createTestRoom("room2")
    orchestrator.AddRoom(room1)
    orchestrator.AddRoom(room2)
    
    door := spatial.CreateDoorConnection("door1", "room1", "room2", 1.0)
    orchestrator.AddConnection(door)
    
    // Test managed placement and transition.
    entity := createTestEntity("hero")
    _, err := orchestrator.PlaceEntity(&spatial.PlaceEntityInput{
        RoomID: "room1", Entity: entity, Position: spatial.Position{X: 5, Y: 5},
    })
    assert.NoError(t, err)
    roomID, exists := orchestrator.GetEntityRoom("hero")
    assert.True(t, exists)
    assert.Equal(t, "room1", roomID)

    transitioned, err := orchestrator.TransitionEntity(&spatial.TransitionEntityInput{
        EntityID: "hero", FromRoom: "room1", ToRoom: "room2", ConnectionID: "door1",
    })
    assert.NoError(t, err)
    _, exists = orchestrator.GetEntityRoom("hero")
    assert.False(t, exists, "transition is unplaced until managed placement")
    _, err = orchestrator.PlaceEntity(&spatial.PlaceEntityInput{
        RoomID: "room2", Entity: transitioned.Entity, Position: spatial.Position{X: 1, Y: 1},
    })
    assert.NoError(t, err)
    roomID, exists = orchestrator.GetEntityRoom("hero")
    assert.True(t, exists)
    assert.Equal(t, "room2", roomID)

    // Test pathfinding
    path, err := orchestrator.FindPath("room1", "room2", entity)
    assert.NoError(t, err)
    assert.Equal(t, []string{"room1", "room2"}, path)
}

Integration with Other Modules

The spatial module integrates seamlessly with other RPG Toolkit modules:

• Events: Automatic event publishing for spatial changes
• Core: Uses core.Entity for type safety
• Conditions: Spatial conditions (e.g., "within 30 feet")
• Spells: Area of effect calculations
• Combat: Movement and positioning
• Resources: Movement costs and ability usage
• Mechanics: Integration with game rule systems

Performance Considerations

• Query Caching: The query system includes built-in caching
• Event Throttling: Consider throttling high-frequency movement events
• Large Grids: For very large areas, consider partitioning rooms
• Memory Usage: Remove entities from rooms when no longer needed

Contributing

When contributing to the spatial module:

1. Ensure all tests pass
2. Add tests for new functionality
3. Follow the existing code patterns
4. Update this README for new features
5. Consider event system integration for new features

License

Part of the RPG Toolkit - see main repository for license information.