Stormworks Gridworld MVP

File Structure + Quick Start

stormworks_poc/
  README.md

  requirements.txt
  run.py

  config/
    settings.py              # grid size, tick rates, capacities, colors, etc.

  sim/
    world.py                 # grid, obstacles, fires, water station, spawn points
    physics.py               # kinematics + collision/stuck detection
    entities.py              # base Entity, Firefighter, Support, and their state
    scheduler.py             # tick loop + role update ordering

  ai/
    addon_ai.py              # “AI Assistant” role: tasking/dispatch logic
    messages.py              # message types + simple bus (Addon<->Vehicles)

  ui/
    renderer.py              # pygame drawing (grid + colored dots + overlays)
    chat.py                  # in-game chat window UI + scrollback
    input.py                 # mouse/keyboard bindings (pause, step, spawn, etc.)

  planners/
    astar.py                 # pathfinding on grid with roadblocks
    navigation.py            # waypoint generation/smoothing, route validity checks

  tests/
    test_astar.py
    test_messages.py

# Create venv 
python3 -m venv sim

# Activate venv (linux)
source sim/bin/activate
# Activate venv (windows)
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass # unnecessary depending on your script running permissions
sim\Scripts\Activate.ps1

# Install requirements
pip install -r requirements.txt

# Run simulation
python run.py

Controls

SPACE - Pause/Resume ↑/↓ - Scroll chat window ESC - Quit

Legend

Gray cells = Roads (vehicles must travel on roads) Red dot = Firefighter (blocked by roadblocks) Green dot = Support (must clear roadblocks to pass) Blue square = Water station Gray squares with X = Roadblocks (block both vehicles) Orange dots = Active fires (on roads) Dark dots = Extinguished fires

Game Mechanics

• Roads: All vehicles must travel along designated roads (gray cells)
• Roadblocks: Block both vehicles until cleared by support
• Support: Can move TO a roadblock to clear it, but cannot pass through roadblocks
• Strategic Clearing: Support must clear roadblocks in sequence to reach blocked areas
• Firefighter: Must wait for support to clear blocking roadblocks before reaching fires
• Fires: Spawn ON roads so they are always reachable once paths are cleared