JEV-Star
StarCraft II research repo where Jev Choices pick macro actions and unit micromanagement, optionally constrained by a larger model's plan.
Overview
JEV-Star brings full-game StarCraft II macro control and SMAC-Hard micromanagement into one repository, with a paper, recorded winning games and replays. The macro module plays real-time Protoss games with 73 actions, where Jev (or a uniform-random baseline) selects actions from available candidates, optionally filtered or advised by an Astra plan from a larger model. The micro module uses PySC2 with SMAC-Hard across 35 maps, where Astra writes one plan per map and Jev selects actions for each living unit.
The design separates frequent action selection, which Jev handles quickly, from longer-term strategy. Selections are validated against available actions before a local executor applies them. The README highlights a macro victory against the hardest non-cheating built-in AI and documents five macro configurations. The validated setup is Windows, Python 3.10 and a specific SC2 client version, with separate virtual environments per module. Documentation is bilingual English and Chinese.
What the decision model decides
| Type | Question | Answers |
|---|---|---|
| Choice | Which available macro action should be taken now? | — |
| Choice | Which action should this living unit take this step? | — |
How it works
- Build structured state and the list of available candidate actions
- Optionally filter or annotate candidates with an Astra plan
- Jev (or random baseline) chooses an action; selection validated
- Local executor applies it in real-time StarCraft II
Strengths
- Paper, videos and 22 winning replays for inspection
- Random baseline included for comparison
- Separates fast tactical choices from slower planning
Caveats
- Validated only on Windows with a specific SC2 build and region
- Research code requiring the SC2 client and a TypeSafe key
Getting started
git clone https://github.com/sc2musa/Jev_Star.git, run `py -3.10 scripts/setup_environment.py macro` (and micro), set SC2PATH and TYPESAFE_API_KEY, then install maps.At a glance
- Type
- Project
- Status
- research
- Language
- Python
- Runtime
- StarCraft II (BurnySC2 / PySC2)
- Has code
- yes
Use cases and integrations
How curated lists describe it
Gaming: uses Jev `Choice` decisions for StarCraft II macro control and micromanagement on 35 SMAC-Hard maps, validates selections against available actions, and follows optional GPT-6 plans to separate frequent action selection from longer-term strategy.
yibie/awesome-jevReal-time StarCraft II macro control in five configurations plus unit micromanagement, with a paper and recorded games.
MrJev/awesome-jev
Frequently asked questions
What does Jev control?
Macro action selection in full games and per-unit actions in SMAC-Hard micromanagement.
What is Astra's role?
An optional larger-model planner that constrains or advises Jev's choices.
Is there evidence it works?
The repo includes a paper, full-game videos and 22 winning replays, including a macro win at the hardest non-cheating difficulty.
Related projects
Real-time bot battles where you write a fighter's strategy in plain English and a System One model pilots it several times a second.
ProjectbetaTypeScriptBot that plays Red Alert 2 web skirmishes, with code handling mechanics and a decision model making stance, threat and timing calls.
ServicebetaPythonMultiplayer 3D science-fantasy version of Houston's River Oaks District with Jev-powered NPC companion, chauffeur and smart drive.
ProjectbetaTypeScriptBrowser 3D planetary rover sandbox where a TypeSafe controller chooses the next action from complete candidates, versus a baseline.
ProjectbetaTypeScriptDoom runs as a spacecraft payload over real flight software; Jev pilots from the ground every half second while Claude reviews.
ProjectprototypePythonMinecraft agent where Hermes plans, Jev picks one bounded action at a time and a Mineflayer harness validates and executes.
ProjectprototypeJavaScript