JEV-Star

English | 简体中文

Realtime StarCraft II macro control in five configurations, plus JEV and Astra micromanagement.

五种配置的实时星际争霸 II 宏观控制，以及 JEV 与 Astra 微操。

Read the paper / 在线阅读论文 · PDF · Video gallery / 视频展示 · Citation / 引用

Videos / 视频

Play the full winning games directly below. 22.4 fps, original speed, complete matches.

点击下方播放器即可观看完整胜局，22.4 fps、原速播放。

M01 · Macro VeryHard / Elite victory / 宏观最高非作弊难度胜局

macro-v2.1 / Astra + JEV · 12:47.90

https://github.com/user-attachments/assets/5cab5e0a-e8c4-43b8-a504-96f916f73e2a

M02 · Macro Easy victory / 宏观 Easy 胜局

earlier Astra + JEV macro · 15:04.20

https://github.com/user-attachments/assets/2beaa558-67d5-4b7f-8a8d-c29f4359ab36

U01 · Micro mmmt victory / 微观 mmmt 胜局

C / P0 Astra + JEV / schema 7 · 00:21.43

https://github.com/user-attachments/assets/48b26ba0-63be-45c4-82a5-f4bb6814f73e

English

JEV-Star brings full-game macro control and SMAC-Hard micromanagement into one repository. Each module has its own environment, action space, and experiment records:

flowchart LR
    S[Structured state] --> C[Available candidates]
    S --> A[Optional Astra plan]
    A -->|Constrained mode| F[Plan filtering]
    C --> F
    F --> D[JEV or uniform random]
    C -->|No plan filtering| D
    A -->|Context| D
    D --> E[Local executor]
    E --> G[Realtime StarCraft II]

Videos and replays

The players at the top of this README show three complete winning games. Media details and 22 original winning replays. Selected victories are shown separately from the complete evaluation results below.

Quick start

The validated setup is Windows, Python 3.10, and SC2 5.0.16.97563 installed for the Asia region (kr). Install the SC2 client separately; matches are created through the local SC2 API. The two modules use separate virtual environments to keep their SC2 SDK dependencies isolated.

git clone https://github.com/sc2musa/Jev_Star.git
cd Jev_Star
py -3.10 scripts/setup_environment.py macro
py -3.10 scripts/setup_environment.py micro --video

$env:SC2PATH = 'C:\game\StarCraft II'
$env:TYPESAFE_API_KEY = '<your TypeSafe API key>'
py -3.10 scripts/install_maps.py all

Alternatively, copy config.example.md to a local config.md. Git ignores the real key file. Astra planning uses an authenticated native Codex CLI installation; use --codex-path to specify its executable explicitly.

Before running macro games, launch the installed SC2 client once to generate stableid.json, then synchronize the BurnySC2 enums. Use the version of your installed client:

& .\.venvs\macro\Scripts\python.exe -B scripts/sync_sc2_ids.py --game-version 5.0.16.97563

Run one macro game:

py -3.10 jev_star.py macro --planner codex --planner-effort medium --map 'Altitude LE' --opponent-race Zerg --difficulty Easy --game-time-limit 1200

Run three micro episodes on 3m:

py -3.10 jev_star.py micro --map 3m --episodes 3 --planner codex --planner-effort medium --planner-timeout 180 --request-timeout 15 --max-requests 10000

Use py -3.10 jev_star.py macro --help or micro --help for all options. Relative paths in forwarded arguments are resolved inside macro/ or micro/.

Experiment status

Each micro version was evaluated on 35 maps with three episodes per map. JEV alone achieved 3 wins, 2 draws, and 100 losses; the earlier Astra + JEV version achieved 6 wins, 1 draw, and 98 losses; P0 Astra + JEV achieved 7 wins and 98 losses. Excluding the two development maps, the three versions achieved 3/99, 3/99, and 7/99 wins, respectively.

Macro supports five configurations, separating planner presence, plan-based constraints, and the action selector. The selected Lv7 batches use realtime play, Altitude LE, Protoss versus Zerg, seeds 1–10, and a 20-minute game-time limit.

* Nine replay-verified losses and one human-adjudicated loss without a saved replay. There are 50 selected attempts and 49 verified replays. The JEV-only row now includes ten realtime Lv7 games; its earlier Lv2 case and the entire four-attempt SDK-compatibility pilot are excluded. Archived version and service-timing differences prevent a single-variable causal interpretation.

The game advances during inference: all 19,605 JEV responses and 509 Astra responses across the primary batches span advancing game frames. JEV median response times are 0.391 s (JEV-only), 0.375 s (constrained), and 0.421 s (advisory). Advisory means Astra does not filter actions; executor availability and command-lifecycle rules still apply. Micro remains fixed-step.

The advisory row includes concise Astra prompt targets and an independent 20-second army-command guard; retreat remains available under base rules. Advisory experiment and diagnostics · Pure-random realtime experiment.

Five configurations and runnable commands · Per-game evidence. The consolidated release uses the final Astra implementation. 140 macro and 37 micro offline tests pass; no paid games are required by the test suites.

Experiments and version boundaries · Architecture and data flow · Logs and replays · Paper PDF · Paper source and data

Repository layout

macro/       Macro controller, tests, and six ladder maps
micro/       Micro controller, PySC2/SMAC-Hard runtime, tests, and 35 maps
scripts/     Environment setup, map installation, and SC2 enum synchronization
docs/        Architecture, experiments, cleanup notes, and source manifest
paper/       Current paper, LaTeX source, figures, and fixed analysis data
licenses/    Upstream licenses
jev_star.py  Unified command entry point for the two isolated environments

Run outputs are stored under each module's jev_runs/ directory. Full events, generated replays and videos, virtual environments, credentials, and machine diagnostics are excluded from Git; the original research archives remain in the local workspace. Reviewed full-length videos under media/videos/ and original winning replays under media/replays/ are included. The README uses GitHub's native inline video players; original higher-bitrate recordings are also archived in Releases. The repository also includes the paper's fixed statistical tables. Excerpts do not replace complete original logs.

Tests

Push-Location macro
& ..\.venvs\macro\Scripts\python.exe -B -m unittest discover -s tests -p 'test_jev*.py'
Pop-Location
Push-Location micro
& ..\.venvs\micro\Scripts\python.exe -B -m unittest discover -s tests -p 'test_jev*.py'
Pop-Location

Tests use mocked interfaces and do not launch the game or call paid models. GitHub Actions runs the same two offline test suites. See the cleanup record for the scope of the initial publication checks.

Upstream sources

Macro is based on LLM Play SC2. Micro is based on SMAC-Hard and its bundled PySC2. Original source notices and applicable licenses are retained; see third-party notices and the source manifest.

简体中文

JEV-Star 将完整对局的宏观控制与 SMAC-Hard 微操放在同一个仓库中维护。两个模块各有独立环境、动作空间和实验记录：

flowchart LR
    S[Structured state] --> C[Available candidates]
    S --> A[Optional Astra plan]
    A -->|Constrained mode| F[Plan filtering]
    C --> F
    F --> D[JEV or uniform random]
    C -->|No plan filtering| D
    A -->|Context| D
    D --> E[Local executor]
    E --> G[Realtime StarCraft II]

胜局视频与回放

本页上方可直接播放 3 场完整胜局。视频说明与 22 份原始胜局 replay。这里展示选定胜局，完整实验成绩见下文。

快速开始

已验证环境为 Windows、Python 3.10、SC2 5.0.16.97563 亚服 kr 安装。SC2 客户端需自行安装；对局通过本地 SC2 API 创建。使用两个虚拟环境，避免不同 SC2 SDK 的依赖互相覆盖。

git clone https://github.com/sc2musa/Jev_Star.git
cd Jev_Star
py -3.10 scripts/setup_environment.py macro
py -3.10 scripts/setup_environment.py micro --video

$env:SC2PATH = 'C:\game\StarCraft II'
$env:TYPESAFE_API_KEY = '<your TypeSafe API key>'
py -3.10 scripts/install_maps.py all

也可将 config.example.md 复制为本地 config.md。实际密钥文件已被 Git 忽略。Astra 规划使用已登录的原生 Codex CLI；通过 --codex-path 可以显式指定它的路径。

宏观实战前，应启动一次安装好的 SC2 以生成 stableid.json，再同步 BurnySC2 枚举；版本号以实际客户端为准：

& .\.venvs\macro\Scripts\python.exe -B scripts/sync_sc2_ids.py --game-version 5.0.16.97563

宏观一局：

py -3.10 jev_star.py macro --planner codex --planner-effort medium --map 'Altitude LE' --opponent-race Zerg --difficulty Easy --game-time-limit 1200

微观 3m 三局：

py -3.10 jev_star.py micro --map 3m --episodes 3 --planner codex --planner-effort medium --planner-timeout 180 --request-timeout 15 --max-requests 10000

所有参数可通过 py -3.10 jev_star.py macro --help 或 micro --help 查看。转发参数中的相对路径以 macro/ 或 micro/ 为基准。

实验状态

微观每版 35 图 × 3 局：纯 JEV 为 3 胜、2 平、100 负，旧 Astra＋JEV 为 6 胜、1 平、98 负，P0 Astra＋JEV 为 7 胜、98 负。排除两张开发地图后，三版分别为 3/99、3/99、7/99 胜。

宏观按规划、计划约束和底层选择器分成五种配置。选定 Lv7 批次均为 实时运行：Altitude LE、Protoss 对 Zerg、种子 1–10、每局 20 分钟游戏时限。

* Astra＋随机含 9 局回放验证败北和 1 局人工确认败北，该局没有保存回放。共 50 次选定对局、49 份已验证回放。纯 JEV 已补齐实时 Lv7 十局；早期 Lv2 案例与整批四次 SDK 兼容性试跑均不计入主表。固定种子开发样本仍有源码版本和服务时序差异，不称为完全受控的五组消融。

主表各组的 19,605 次 JEV 回复与 509 次 Astra 回复均跨越了持续推进的游戏帧。JEV 响应中位数为纯 JEV 0.391 秒、约束模式 0.375 秒、建议模式 0.421 秒。“建议模式不限制动作”专指 Astra 不按计划过滤，执行器可用性及命令生命周期规则保留。微观仍使用固定步进。

建议组包含 Astra 简洁文本提示与独立的 20 秒军队指令防抖，撤退保持基础合法性。建议组实验与诊断 · 纯随机实时实验。

五种配置和运行命令 · 逐局证据。当前代码统一采用最终 Astra 实现，140 项宏观、37 项微观离线测试通过，测试不启动付费对局。

实验与版本边界 · 架构与数据流 · 日志和回放 · 论文 PDF · 论文源码及统计表

目录

macro/       宏观控制代码、测试和六张梯图
micro/       微操代码、PySC2/SMAC-Hard 运行底层、测试和 35 张地图
scripts/     环境安装、地图安装和 SC2 枚举同步
docs/        架构、实验、整理说明和源文件清单
paper/       当前论文、LaTeX 源码、图表和固定统计数据
licenses/    上游许可证
jev_star.py  两个独立环境的统一命令入口

运行结果保存在各模块的 jev_runs/ 下。完整事件、新生成的 replay 和视频、虚拟环境、密钥和本机诊断文件默认不进入 Git；已有原始研究档案保留在本地工作区。已核验的完整视频收录在 media/videos/，胜局 replay 收录在 media/replays/。README 使用 GitHub 原生播放器，原始高码率录像另存于 Releases。仓库也包含论文的固定统计表，完整原始日志不以节选代替。

测试

Push-Location macro
& ..\.venvs\macro\Scripts\python.exe -B -m unittest discover -s tests -p 'test_jev*.py'
Pop-Location
Push-Location micro
& ..\.venvs\micro\Scripts\python.exe -B -m unittest discover -s tests -p 'test_jev*.py'
Pop-Location

测试使用模拟接口，不启动游戏或付费模型。GitHub Actions 使用同样的两组离线测试。首次公开整理的验证范围见 整理记录。

上游来源

宏观基于 LLM Play SC2；微观基于 SMAC-Hard 及其 PySC2。保留对应源代码声明与许可证，详见 第三方说明 和 源文件清单。

Citation / 引用

If you use JEV-Star in your research, please cite the paper below. You can also use Cite this repository in the GitHub sidebar to copy an APA or BibTeX citation.

如果本项目对你的研究有帮助，请引用以下论文；也可以点击 GitHub 侧栏的 Cite this repository，复制 APA 或 BibTeX 引用。

Weiyu Ma, Liangbing Zhao, Yongcheng Zeng, and Jian Zhao. 2026. JEV-Star: Fast, Low-Cost StarCraft II Control with Language-Model Planning. Preprint.

@misc{ma2026jevstar,
  title = {{JEV-Star}: Fast, Low-Cost {StarCraft II} Control with Language-Model Planning},
  author = {Ma, Weiyu and Zhao, Liangbing and Zeng, Yongcheng and Zhao, Jian},
  year = {2026},
  month = sep,
  note = {Preprint},
  url = {https://github.com/sc2musa/Jev_Star/blob/main/paper/PAPER.md}
}

BibTeX file / BibTeX 文件 · Citation metadata / 引用元数据 · Read the paper / 在线阅读论文