BAR ProcMap Lab

Procedural map source generator and preview UI for Beyond All Reason / Recoil experiments.

This project is an early open-source MVP for quickly generating simple, readable, playable-ish map source assets: rolling hills, plains, flattened starts, basic water, safe/contested metal, and preview images. It is intended as a foundation for later BAR/Recoil map packaging and campaign integration work.

Status

Current prototype:

• deterministic map generation from seed
• up to 32 spawn spots for 16v16 team tests
• two-side/team, diagonal, opposing-corner diagonal, 2x4 mirrored, 4x4 mirrored, and radial/FFA spawn layouts
• cliffiness/terrace control for ridge and plateau experiments
• random tree and rock feature placement, with preview markers and features.json output
• local browser UI with parameter controls
• instant latest preview image
• preview gallery of generated maps
• clickable generated assets from the UI
• CLI generator
• unit tests
• local BAR/Recoil headless smoke test: verifies generated preview PNG loading, writes a startscript, runs BARb-vs-BARb on a known installed map, and auto-terminates
• visible BAR/Recoil spectator test using spring.exe, so you can watch BARb-vs-BARb until auto-timeout on a known installed stock map
• MVP generated-map export: writes minimal .smf/.smt into a development .sdd, installs it under the local BAR maps dir, and can launch the selected generated map visibly

Not implemented yet:

• finished .sd7 map export
• SMF/SMT compilation
• BAR lobby/menu integration
• in-engine map enumeration smoke test
• polished .sd7 archive export; current generated-map export uses development .sdd directories
• high-quality/fast native map compiler integration; current MVP uses a pure-Python SMF/SMT/DXT1 writer
• direct GUI BAR launch button
• competitive balance scoring

Generated files

Each generated map artifact is saved under outputs/<timestamp>-<seed>-<name>/:

• height.png — grayscale heightmap
• metal.png — grayscale metal map
• texture.png — simple biome texture
• preview.png — shaded preview with start and metal markers
• mapinfo.lua — starter metadata placeholder
• starts.json — start positions
• features.json — generated tree/rock feature placements
• terrain.json — parameters and generated metadata

outputs/ is gitignored because these are local/generated artifacts.

Run the UI

python -m bar_procmap_lab.server --host 127.0.0.1 --port 8766

Open:

http://127.0.0.1:8766

The UI shows the latest generated preview and a gallery of previous generated previews. Each gallery card links directly to preview.png, terrain.json, height.png, metal.png, and texture.png.

CLI generation

python -m bar_procmap_lab.generate_cli --seed 42 --size 512 --players 2 --hilliness 0.45 --metal 0.7 --output outputs/test-map

Test

python -m unittest discover -s tests -v

Generated BAR/Recoil map export MVP

After generating or selecting an artifact, use the UI buttons:

• Export selected as BAR map
• Run GENERATED map visible spectator (3 min)

CLI equivalent:

python -m bar_procmap_lab.bar_export_cli outputs/test-map --spring-size 8
python -m bar_procmap_lab.bar_export_cli outputs/test-map --spring-size 8 --visible-test --duration-seconds 180

The UI exposes BAR export sizes 4, 8, 16, 32, and 64. The current pure-Python exporter can technically target those dimensions, but cost grows quadratically: 64x64 implies a 32768x32768 source texture and roughly 680 MB of SMT tile data, so it is experimental/heavy. 4x4 and 8x8 are the practical smoke-test sizes right now.

This MVP does not use external springMapConvNG; it writes a minimal SMF/SMT package directly in Python, including a simple DXT1 tile/minimap encoder. It installs an unpacked development map under the local BAR maps directory:

C:\Program Files\Beyond-All-Reason\data\maps\<map>.sdd

The launch name currently includes the map version suffix parsed by Recoil, for example:

ProcMapLab_RealExportSmoke_20260730 1

This is verified to enumerate and load locally. Visual quality is smoke-test grade; a native compiler path or better DXT/color/tile handling can improve final map appearance later. Generated-map spectator launches use fixed start positions (startpostype=0) so BAR does not pause in the pregame/manual placement flow with messages such as MINIMAP NOT READY.

BAR/Recoil headless smoke battle

After generating an artifact, you can run a bounded local BAR smoke test:

python -m bar_procmap_lab.bar_smoke_cli outputs/test-map --duration-seconds 180

For a visible spectator window instead:

python -m bar_procmap_lab.bar_visible_cli outputs/test-map --duration-seconds 180

Important: the smoke/visible tests do not yet launch the generated terrain. They use the selected artifact for preview PNG validation and log/result grouping, then launch BARb-vs-BARb on a known installed stock map (Seven Rivers v1.21) using the latest local BAR/Recoil engine. It verifies the generated artifact's preview.png is a valid PNG, writes a BAR startscript, launches a BARb-vs-BARb headless match, records the log/result under <artifact>/bar_smoke/, and terminates the process after the requested duration.

The size selector controls generated source-image resolution, not final BAR map dimensions. Native BAR maps can be much larger in gameplay terms; the eventual exporter needs a separate pixels-to-map-squares scale. Current pure-Python generation is capped at 2048 px to keep local preview generation reasonable.

This does not yet compile the generated height/metal/texture images into a playable .sd7 map; that remains the next exporter milestone.

Design bias

The generator intentionally prioritizes boring-but-playable terrain over wild noise:

• smoothed octave value-noise terrain
• flattened circular start areas
• symmetric/radial start placement
• safe base metal plus contested midfield metal
• readable biome texture
• deterministic output from seed

Roadmap

1. Add a real BAR/Recoil exporter/packager target.
2. Validate generated packages with local BAR/Recoil map enumeration.
3. Add slope/pathing heuristics and reject bad seeds.
4. Add richer terrain archetypes: open plains, central ridge, valley, islands, chokepoints.
5. Add generated map thumbnails to GitHub release artifacts once package export exists.
6. Explore BAR-side UI integration after the backend/export path is stable.

License

MIT. See LICENSE.