Asset Pipeline — Wargame Engine + LangGraph Hex Grid

Status: ACTIVE (concept exploration) Agent: opencode/ext-agent (sandshrew) Timestamp UTC: 2026-05-11T20:10:00Z Claim: analysis | 2026-05-11T20:08:00Z Session: Asset handling methodology for LangGraph game surface on Wargame Engine

Prior Context

• [[wargame-engine-rg-deployment]] — Confirmed Wargame Engine runs on RG
• [[langgraph-hex-node-mapping]] — Hex-to-node mapping architecture
• [[langgraph-unit-node-interaction-model]] — Unit/state/node model

What Wargame Engine Provides

Wargame Engine includes built-in asset loaders: - GuiImage.from_image('sprites.dog') — loads from a sprite namespace - Image loaders for sprites and backgrounds - Sound loaders for audio - Config file loaders (for game data)

It does NOT include: - A map editor - A tile editor - A sprite creation tool - Any asset creation pipeline

Assets must be created externally and loaded in. The engine provides the rendering pipeline, not the content.

Two Stages: Prototype vs Production

Prototype (Now): Zero-Asset Approach

For the architectural prototype (10 units, small hex grid, prove LangGraph↔Wargame loop works):

No external assets needed.

Every visual can be generated in code: - Hex tiles: pygame.draw.polygon() — colored hexagons. Green = grass, dark green = forest, blue = water, brown = mountain - Units: pygame.draw.circle() or small rectangles with text labels - UI panels: pygame.draw.rect() with text (pygame.font) - Font: Wargame Engine's built-in font rendering or pygame's default font

This is 50-100 lines of rendering code. It proves the architecture. Real assets are a swap-in replacement — they slot into the same rendering positions.

# Prototype hex rendering — no external assets
def render_hex(screen, hex_node, state):
    terrain = state["terrain"][hex_node]
    color = TERRAIN_COLORS[terrain]  # {"grass": (50,150,50), "forest": (20,80,20), ...}
    draw_hex_polygon(screen, color, hex_to_pixel(hex_node))

    if state["units_in_hex"][hex_node]:
        for unit in state["units_in_hex"][hex_node]:
            # Unit = colored circle + name label
            pygame.draw.circle(screen, UNIT_COLORS[unit["role"]], center, 12)
            draw_text(screen, unit["name"], center)

Production (Later): Asset Swap-In

When the architecture is proven and visual polish matters:

The rendering code doesn't change — only the sprite reference changes:

# Production: swap shape for sprite
# Before:
pygame.draw.circle(screen, color, center, 12)
# After:
sprite = wargame.GuiImage.from_image(f'units.{unit["role"]}')
screen.blit(sprite, center)

Map Data: Two Approaches

Approach A: Map as LangGraph State (Recommended)

The map IS the graph. Node definitions, edges, and terrain types live in LangGraph state. No external map file needed.

# Map defined in state — loaded at graph initialization
map_state = {
    "nodes": {
        "hex_00": {"terrain": "grass", "position": (0, 0)},
        "hex_01": {"terrain": "forest", "position": (1, 0)},
        # ...
    },
    "edges": {
        "hex_00": ["hex_01", "hex_10"],
        "hex_01": ["hex_00", "hex_02", "hex_11"],
        # ...
    }
}

This keeps the map as part of the graph state, checkpointable, and modifiable at runtime (procedural generation, terrain changes).

Approach B: External Map File

If maps need to be authored in a visual tool: - Tiled editor (https://www.mapeditor.org/) — export as JSON → load into LangGraph state - Custom JSON/YAML — handwritten or generated - Procedural generation — Python script that populates LangGraph state

The map is loaded once at graph initialization, then lives in state forever. No reload needed.

Asset Storage and Bundling for RG40XXV

For PortMaster distribution:

game-surface/
├── assets/
│   ├── sprites/         # terrain tiles, unit icons
│   │   ├── grass.png
│   │   ├── forest.png
│   │   └── units.png    # or sprite sheet
│   ├── ui/              # panels, buttons, frames
│   └── audio/           # SFX, ambient
├── maps/
│   └── campaign_01.json # optional — if using external map files
├── src/                 # game code
└── Game-Surface.sh      # launcher

Observational Note: Assets Are Not the Bottleneck

The hard part of this project is the architecture: LangGraph as state authority, Wargame as rendering layer, HTTP bridge between Pi and RG, access gating, per-node config overrides, intel harvesting, the turn cycle. All of these are solved in code, not in assets.

Assets are a rendering concern that can be handled in three phases: 1. Now: Colored shapes + text. Prove the architecture. Zero asset work. 2. Soon: Simple pixel art hex tiles (a few hours in Aseprite). Elevate the visual baseline. 3. Later: Production sprites, animations, audio. Swap in without code changes.

The rendering code should be written to accept any visual — shape, sprite, or animation — at the same position. The architecture doesn't care what the hex looks like. The state doesn't change. Only the renderer's draw_hex() function changes.