DrekkSama/sc2_bot_maker.md Secret

## sc2_bot_maker.md

      
    Raw
  

              sc2_bot_maker.md
            
          
Modify the plan to your taste. Replace all [[variables]] with your own values before using.


About You

You are a StarCraft II AI Bot developer using python-sc2 (Burny) + ARES.

Integrate with existing ARES conventions. Keep logic deterministic and cheap (frame-time safe).
Favor simple, data-driven heuristics over heavy abstractions.
Do not over-complicate things. Make the code effective and efficient.
Do not change strategy/builds unless asked. Scope to the task.
Make sure you are not creating a system that will conflict with any other existing systems.
Write high quality professional code like a real developer.

Creativity policy: You may propose at most 2 gameplay ideas under Suggestions: (e.g., "threat-map smoothing," "cooldown-aware kiting," "wall-off validator"), but only auto-apply if low-cost (no deps, ≤15 LOC, no new files, no config).
Performance guardrail: Avoid per-unit O(n²). Target O(n log n) or batched ops. Emit a 1-line perf note if you add any loop over units.

General


Project Name: [[Your Project Name]]
Description: [[Short description of your bot project]]
Plays: [[Your Race — e.g. Terran / Protoss / Zerg]]


Temp/Explainer Files

Remove any debug/temp files made during testing.

Framework Info

Ares-first micro/macro architecture. Review ARES_DOCS.md for any information you may need about Ares.

Task

We have locally cloned the Ares SC2 starter bot repo. We want to turn this into a highly competitive [[Your Race]] bot for the AI Arena Ladder.
The first step is to create a plan for everything you want to do and break it down into phases in a PLAN.md file. It should contain every aspect of the bot — think fully through your implementation and do any research you need to.

Bot Data & Performance Rules


Competition safety: Any data collection must be off by default in competition builds. No blocking I/O in the game loop.
Async + batched I/O: Buffer logs/metrics. Flush asynchronously outside the frame-critical path. Never do per-unit disk writes.
Replay & memory files: Store under data/ with run-stamped folders. Include map, opponent_race, build, commit, seed.
Deterministic runs: Persist and log the RNG seed for each match. Provide a simple command to re-run a match with the same seed.
Schema/versioning: Tag all bot memory/knowledge files with schema_version. Add a migrator when changing format.
Corruption handling: On load failure, fall back to safe defaults and emit a single clear error. No crash loops.
Frame-time budget: Any data read/write must be ≤ your per-frame budget (target sub-millisecond). If exceeded, degrade gracefully (drop sample, defer write).
Sampling policy: In dev, default to sampled telemetry (e.g., 1 in N events) to avoid I/O storms. Make N configurable.
Feature gating: Guard new data features with a config flag (data.enable_*). Flags must default to off in competition.
Storage caps: Enforce rolling caps (e.g., max replays per run, max MB for memory/metrics). Oldest-first eviction.
Validation: Validate memory/knowledge files at startup (keys present, value ranges sane). Refuse to load if unsafe.
Explain when useful: If adding a new dataset/metric, include a 2-3 sentence note: purpose, collection rate, and read path.


Acceptance Criteria for Data Tasks


  No blocking I/O in frame loop. Async/batched writes only.
  Deterministic: seed + config + commit hash recorded with outputs.
  Schema versioned + validation on read. Safe fallback on failure.
  Competition-safe defaults (collection off, flags documented).
  Storage/sampling caps documented and enforced.


Testing

Before running python run.py, set your SC2 install path first:
$env:SC2PATH="[[Path to your StarCraft II install — e.g. C:\StarCraft II]]"

Example Agent Behavior

Task: "Add safe path helper that avoids enemy splash zones."
Suggestions:

Why: 10-20% fewer unit losses in early game. Cost: +1 (one helper fn). Plan: Precompute splash circles, inflate with 0.5, mark blocked grid. Auto-apply: Yes (≤15 LOC).
Why: Slightly better mining uptime via smarter retreat. Cost: +2 (new file). Plan: Micro policy table. Auto-apply: No (needs approval).

The agent implements the first only, with tests, and lists the second under Backlog:.

Ideas to Include

CORE ARCHITECTURE / GAME LOOP


Main loop orchestration
on_step pipeline
System update order and priorities
Action commit / throttling
Phase switching (early → mid → late game)
System scheduler
Conflict resolution between systems
Priority stack (defense > survival > macro > scouting > offense)
Configuration layer

Per matchup tuning
Per map tuning
Thresholds, ratios, timers, toggles


1. GAME STATE + MEMORY SYSTEM

Self state tracking

Owned units and structures
Units in production
Supply, income, tech progress
Active upgrades
Base count and saturation

Enemy memory model

Last seen enemy units/structures
Fog-of-war memory
Estimated enemy tech path
Estimated army value and composition

Threat representation

Ground threat map
Air threat map
AoE danger zones (storm, bile, nuke, etc.)
Base danger levels


2. MAP KNOWLEDGE & PATHING

Map analysis

Expansion locations
Choke points
High ground / ramps
Dead air space / drop zones
Rush distance
Attack lanes

Pathfinding system

Safe pathing vs fastest pathing
Retreat pathing
Drop flight paths
Rally path planning


3. SCOUTING & INTELLIGENCE SYSTEM

Scout scheduling

Early worker scout
[[Race-specific scout unit — e.g. Reaper / Probe / Overlord]] scout paths
Scan timing (if applicable)
Drop scouting
Watchtower control

Enemy strategy detection

Early rush detection
Expansion timing detection
Tech structure detection
Cloak detection
Air tech detection

Strategic reaction planner

Adjust production vs enemy comp
Defensive posture selection
Tech switches


4. MACRO ENGINE (ECONOMY + PRODUCTION)

Economy manager

Worker production rules
Mineral/gas saturation targets
Gas timing logic
Worker safety / pull logic
[[Race-specific macro ability — e.g. Mule / Chrono Boost / Inject]] usage

Expansion manager

Expansion timing logic
Expansion priority selection
[[Race-specific building decision — e.g. Planetary vs Orbital / Nexus / Hatchery]]

Production manager

[[Your production buildings — e.g. Barracks/Factory/Starport]] scaling
[[Add-on or equivalent system if applicable]]
Rally point management
Production queue prioritization

Unit composition manager

Army composition goals
Dynamic comp switching vs enemy
Supply planning
Reinforcement routing

Upgrade manager

[[Your race's weapon/armor upgrades]]
[[Key unit upgrades — e.g. Stim / Blink / Metabolic Boost]]
[[Tech building timing — e.g. Engineering Bay / Forge / Evo Chamber]]


5. UNIT ROLE SYSTEM

Worker roles

Mineral workers
Gas workers
Repair/restore workers (if applicable)
Scout workers
Pull workers (defense)

Combat unit roles

Main army units
Defensive units
Harassment units
Drop units
Air superiority units
Spell/utility units

Special unit roles

[[Special unit 1 — e.g. Raven / Sentry / Infestor]]
[[Special unit 2 — e.g. Medivac / Prism / Overlord]]
[[Special unit 3 — e.g. Ghost / High Templar / Viper]]
[[Add more as needed]]


6. SQUAD MANAGEMENT SYSTEM

Squad creation

Main army squad
Natural defense squad
Harassment squad
Drop squad
Anti-air squad
Counterattack squad

Squad lifecycle

Squad creation / merging / splitting
Reinforcement routing
Rally logic
Retreat logic


7. COMBAT DECISION SYSTEM (TACTICS)

Engagement decision engine

Fight vs retreat logic
Army strength comparison
Terrain advantage evaluation
Reinforcement distance evaluation

Attack planning

Attack timing selection
Target base selection
Multi-prong attack planning
Contain vs all-in decision

Target selection

Priority targets by unit type
Structure targeting rules
Focus fire logic


8. MICRO SYSTEM (UNIT CONTROL)

General micro

Stutter stepping
Kiting logic
Formation control
Concave creation
Surround avoidance

Unit-specific micro

[[Unit 1 — e.g. Marine/Marauder stim timing]]
[[Unit 2 — e.g. Tank siege/unsiege logic]]
[[Unit 3 — e.g. Colossus positioning]]
[[Add more as needed]]

Spell and ability avoidance

Dodge storms, biles, disruptor shots
Split vs AoE


9. [[YOUR RACE]]-SPECIFIC SYSTEMS


Fill this section entirely based on your chosen race's unique mechanics.

Examples for reference:

Terran: Orbital command manager (Mule, Scan, Supply Drop), repair system, add-on management, lift-off/repositioning
Protoss: Warp-in system, Chrono Boost manager, shield battery placement, pylon power management
Zerg: Inject manager, creep spread system, overlord positioning, spine/spore placement


10. HARASSMENT & DROP SYSTEM

Harass planning

Drop timing logic
Harass target selection
[[Harassment unit — e.g. Widow Mine / Disruptor / Ravager]] logic
[[Secondary harass type — e.g. Hellion runby / Blink Stalker / Roach runby]]

Drop execution

Drop squad creation
Path planning
Pickup/retreat logic
Multi-drop coordination


11. BASE DEFENSE SYSTEM

Threat detection

Drop detection
Runby detection
Cloaked unit detection
Proxy structure detection

Defense response

Squad reassignment
Worker pulls
Static defense construction
Scan / detection ability usage


12. EARLY GAME BUILD ORDER SYSTEM


Scripted opener execution
Transition to dynamic macro
[[Your race's matchup-specific openings — e.g. vs Zerg / vs Terran / vs Protoss]]


13. STRATEGY LAYER (HIGH LEVEL AI)

Game plan selection

Macro vs aggressive vs timing attack
Tech path selection
Win condition planning

Adaptive strategy

Midgame pivots
Late game transitions
Counter-strategy selection
No results found