Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
81 changes: 81 additions & 0 deletions .github/workflows/native-build.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,81 @@
name: native-build

on:
workflow_dispatch:
pull_request:
branches: [main]
push:
branches: [main]

permissions:
contents: read

concurrency:
group: native-build-${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true

jobs:
build:
name: ${{ matrix.platform.name }} / Python ${{ matrix.python }}
runs-on: ${{ matrix.platform.runner }}
strategy:
fail-fast: false
matrix:
python: ['3.12']
platform:
- {name: linux-x64, runner: ubuntu-22.04}
- {name: windows-x64, runner: windows-latest}
- {name: macos-arm64, runner: macos-15}
- {name: macos-x64, runner: macos-15-intel}
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: ${{ matrix.python }}
- uses: dtolnay/rust-toolchain@stable
- name: Install import dependency
run: python -m pip install "numpy>=1.26,<3"
- name: Build engine, feature kernels and parallel slots
shell: python
run: |
import os
import subprocess
import sys

env = dict(os.environ, PYO3_PYTHON=sys.executable)
for args in (
['-p', 'arkguard-python'],
['--manifest-path', 'arkguardrl_core/native/Cargo.toml'],
['--manifest-path', 'benchmarks/native_slots/Cargo.toml'],
):
subprocess.run(['cargo', 'build', '--release', '--locked', *args], env=env, check=True)
- name: Collect and import all modules
shell: python
run: |
import importlib
import pathlib
import shutil
import sys
import sysconfig

artifacts = pathlib.Path('artifacts')
artifacts.mkdir()
prefix = '' if sys.platform == 'win32' else 'lib'
suffix = {'win32': '.dll', 'darwin': '.dylib'}.get(sys.platform, '.so')
for directory, name in (
('target/release', '_native'),
('arkguardrl_core/native/target/release', '_rust_routes'),
('benchmarks/native_slots/target/release', '_native_slots'),
):
source = pathlib.Path(directory) / f'{prefix}{name}{suffix}'
shutil.copy2(source, artifacts / f'{name}{sysconfig.get_config_var("EXT_SUFFIX")}')
sys.path.insert(0, str(artifacts.resolve()))
for name in ('_native', '_rust_routes', '_native_slots'):
module = importlib.import_module(name)
assert pathlib.Path(module.__file__).resolve().parent == artifacts.resolve()
print(f'Imported {module.__file__}')
- uses: actions/upload-artifact@v4
with:
name: native-py${{ matrix.python }}-${{ matrix.platform.name }}
path: artifacts/*
if-no-files-found: error
7 changes: 5 additions & 2 deletions AGENTS.md
Original file line number Diff line number Diff line change
@@ -1,10 +1,13 @@
# Scope

Core owns environment/runtime performance; ArkGuardRL owns strategy research.
Maintain only Desperation mode (`mode_single_abyss`). Scope migration work,
new content and acceptance to this mode; other modes are not maintenance targets.
Do not add standard-mode-only content such as enemy-debuff tactical cards.
Keep code and documentation small. Do not add source manifests, binary fingerprints,
release checklists or source-bound checkpoint gates. Preserve model/input
compatibility, memory bounds and valid rollout semantics. Do not run games or
training merely to clean up files or edit documentation.

`main` is frozen at `6af66bf`. Keep multi-env scheduling experiments on
`codex/multi-env-worker`; do not advance or merge into main without user direction.
Multi-environment execution and vectorized runtime work are part of Core and
may be included in PRs targeting main. Continue vectorization work in Core.
3 changes: 3 additions & 0 deletions Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

50 changes: 24 additions & 26 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,30 +3,34 @@
[![Python](https://img.shields.io/badge/python-3.10%2B-3776AB?style=flat-square&logo=python&logoColor=white)](https://www.python.org/)
[![Rust](https://img.shields.io/badge/rust-PyO3%200.27-dea584?style=flat-square&logo=rust&logoColor=white)](https://www.rust-lang.org/)
[![Gymnasium](https://img.shields.io/badge/gymnasium-%E2%89%A51.1-4B8BBE?style=flat-square)](https://gymnasium.farama.org/)
[![Engine](https://img.shields.io/badge/engine-app%200.3.1-lightgrey?style=flat-square)](https://github.com/sganggs/Stronghold-Protocol)
[![Engine](https://img.shields.io/badge/engine-app%200.3.3-lightgrey?style=flat-square)](https://github.com/sganggs/Stronghold-Protocol)
[![License](https://img.shields.io/badge/license-GPL--3.0--or--later-blue?style=flat-square)](LICENSE)
[![Status](https://img.shields.io/badge/status-pre--release-orange?style=flat-square)](docs/NATIVE-033.md)

[Stronghold Protocol](https://github.com/sganggs/Stronghold-Protocol) 的 Gymnasium 环境。

## 安装
当前维护与原生迁移范围仅限绝境(`mode_single_abyss`),进度见 [迁移文档](docs/NATIVE-033.md)。

Python 3.10+、Node 22+
```sh
python -m pip install -e '.[gym]'
```
## 安装与使用

引擎与数据单独准备:[Stronghold-Protocol](https://github.com/sganggs/Stronghold-Protocol)
`c9d804f470b8d7422ae04eb66faf671cef21ad52`(app 0.3.1)
Python 3.10+、Rust stable,以及另行准备的 Stronghold Protocol 0.3.3 数据目录。
本仓库不含游戏素材、数据、权重或轨迹。

## 使用
```sh
python -m pip install -e '.[gym]'
PYO3_PYTHON="$(command -v python)" cargo build --release --locked -p arkguard-python
```

```python
import gymnasium as gym
import arkguardrl_core.gym_env # 注册 ArkGuardRL-v0

with gym.make("ArkGuardRL-v0", engine_root="/path/to/engine") as env:
import arkguardrl_core.native_gym

with gym.make(
"ArkGuardRL-v1",
data_root="/path/to/0.3.3/data",
core="band_sarkazb", # band_amiya / band_sarkazb / band_chen / band_sciurus
native_library="target/release/lib_native.dylib",
) as env:
obs, info = env.reset(seed=42)
done = False
while not done:
Expand All @@ -35,6 +39,8 @@ with gym.make("ArkGuardRL-v0", engine_root="/path/to/engine") as env:
done = terminated or truncated
```

Linux 动态库后缀为 `.so`,CI 提供 Linux x64、Windows x64、macOS Intel/Apple Silicon 的 CPython 3.12 原生模块,详见[构建说明](benchmarks/README.md#跨平台构建)。原生运行时读取数据目录,核心由构造参数指定。`banned` 接受禁用干员 ID,`tick_budget` 控制每次战斗续跑的帧数。

观测是 NumPy `Dict`,动作是**当前候选行索引**:

| 字段 | 形状 / 类型 | 含义 |
Expand All @@ -44,7 +50,7 @@ with gym.make("ArkGuardRL-v0", engine_root="/path/to/engine") as env:
| `schedules` / `experts` | `(max_candidates,) int64` | 候选分组 |
| `action_mask` | `(max_candidates,) int8` | 有效候选行 |

- 候选由公开信息构造;引擎仍可能拒绝合法候选,结果见 `info["accepted"]`。
- 候选由公开参数域构造,游戏规则可能拒绝提交的动作,结果见 `info["accepted"]`。
- padding 或越界索引抛 `InvalidAction`,不替换动作、不推进游戏。
- 候选容量默认 16384,超限报错,不裁剪动作域。
- 自然结束为 `terminated`;`max_decisions` / `max_advances` / `wall_seconds` 耗尽为
Expand All @@ -55,23 +61,15 @@ with gym.make("ArkGuardRL-v0", engine_root="/path/to/engine") as env:
通用 `check_env()` 的无掩码随机动作会选中 padding,请按掩码采样。
- 难度与预算只能在构造时配置,`reset(options=...)` 不接受其他选项。

## 并行与测量

支持 `SyncVectorEnv` / `AsyncVectorEnv`。Async 使用 `spawn` 和共享内存,入口需要
`if __name__ == "__main__"`。每个 env 独占一个 Node 进程,默认填充观测约 2.98 MB/env。
## 并行与回放

```sh
python benchmarks/gym_env.py --engine-root /path/to/engine \
--vector async --envs 4 --steps 256 --repeats 3 --out artifacts/gym-async-4.json
```
Gym 支持 `SyncVectorEnv`/`AsyncVectorEnv`,每个环境拥有独立原生会话;Async 使用 `spawn` 时需要 `if __name__ == "__main__"` 入口。Rust slots 支持 1–64 个环境、显式局部 reset 和部分槽位推进。

## 测试
公开地图与当前模板路线通过 `env.unwrapped.public_spatial()` 读取,增量入口为 `public_spatial_update(key)`。真实记录回归、渲染回放和吞吐命令见[性能与验收说明](benchmarks/README.md)。

原生集成测试需显式提供引擎路径,会实际运行对局:
## Node 兼容入口

```sh
ARKGUARD_ENGINE_ROOT=/path/to/engine python -m unittest discover -s tests -p test_gym_env.py -v
```
旧研究调用可通过 `import arkguardrl_core.gym_env` 注册 `ArkGuardRL-v0`,构造时传入 `engine_root`。该路径使用 Node 22+ 及对应的 0.3.1 引擎/数据;观测与候选布局见上表。

## 文档

Expand Down
32 changes: 23 additions & 9 deletions arkguardrl/candidates.py
Original file line number Diff line number Diff line change
Expand Up @@ -187,9 +187,12 @@ def record(self, state, action, *, result):
if state["phase"] == "PREP" and action["t"] != "g.choice":
self.prep_used += 1

def snapshot(self, state):
def _check(self, state):
if self.progress is None or self.progress["observation_id"] != fingerprint(state):
raise ValueError("Initialize/update history with the real environment result before encoding")

def snapshot(self, state):
self._check(state)
key = self._sync(state)
return {"schema": self.schema, "progress": deepcopy(self.progress), "used": self.prep_used, "limit": PREP_ACTION_LIMIT,
"blocked_count": len(self.attempts.get(key, ()))}
Expand All @@ -210,13 +213,17 @@ class Decision:
history_json: bytes | None = field(default=None, repr=False, compare=False)


def build_decision(state, catalog, history):
def build_decision(state, catalog, history, *, encoder=None, candidate_encoder=None, state_copy=None):
locations, occupied, cells = public_context(state, catalog)
own, public = state["own"], state["public"]
if not isinstance(history, DecisionHistory):
raise ValueError("Explicit native DecisionHistory required")
blocked, actions, seen = history.blocked(state), [], set()
blocked = history.blocked(state) if candidate_encoder is None else ()
actions, seen, prepared = [], set(), None
def add(action):
if candidate_encoder is not None:
actions.append(action)
return
key = action_id(action)
if key in blocked or key in seen:
return
Expand Down Expand Up @@ -284,16 +291,23 @@ def add(action):
add({"t": "g.freeze"})
if shop["level"] < shop["maxLevel"] and own["funds"] >= shop["upgradePrice"]:
add({"t": "g.levelUp"})
from arkguardrl_core.env_actions import piece_actions
for action in piece_actions(state, catalog, (locations, occupied, cells), recovery=recovery):
add(action)
from arkguardrl_core.env_actions import piece_actions, piece_inputs
if candidate_encoder is not None:
prepared = piece_inputs(state, catalog, (locations, occupied, cells), recovery=recovery)
else:
for action in piece_actions(state, catalog, (locations, occupied, cells), recovery=recovery):
add(action)
else:
raise CandidateBlocked("Unsupported actionable native phase")
if not actions:
if not actions and (candidate_encoder is None or prepared is None):
raise CandidateBlocked("History/public domain exhausted; no fallback wait or forced Ready")
snapshot = history.snapshot(state)
observation, features, schedules, experts = encode_decision(state, actions, catalog, snapshot)
if candidate_encoder is not None:
actions, observation, features, schedules, experts = candidate_encoder(
state, actions, catalog, snapshot, prepared)
else:
observation, features, schedules, experts = (encoder or encode_decision)(state, actions, catalog, snapshot)
# Retain the exact history used for the feature tensors, independently of
# subsequent history advancement. Bytes cannot alias mutable progress.
return Decision(deepcopy(state), observation, features, tuple(actions), schedules, experts,
return Decision((state_copy or deepcopy)(state), observation, features, tuple(actions), schedules, experts,
state["personalEnded"], history_json=canonical(snapshot))
21 changes: 17 additions & 4 deletions arkguardrl/catalog.py
Original file line number Diff line number Diff line change
Expand Up @@ -51,11 +51,22 @@ def unique(pairs):
raise ValueError("Public catalog/session data identity mismatch")
if set(loaded) != {"bands", "chess", "items", "tokens", "config", "bonds", "garrisons", "enemies", "choices", "effects"}:
raise ValueError("Missing explicit public catalog files")
self._initialize(loaded)

@classmethod
def from_native(cls, native_catalog):
"""Use the engine-owned external definitions, without a source-checkout gate."""
obj = cls.__new__(cls)
obj.data_sha256 = None
obj._initialize(json.loads(native_catalog.public_tables()))
return obj

def _initialize(self, loaded):
self._data = loaded
# The learning API exposes small public projections, not every artwork,
# description, skill implementation or future-wave table in the dataset.
fields = ("id", "chessId", "tokenId", "bandId", "baseId", "goldenId", "tier", "isGolden",
"position", "placeOnRanged", "isDiy", "itemType", "kind", "rangedTilesOnly",
"position", "placeOnRanged", "isDiy", "diyFor", "itemType", "kind", "rangedTilesOnly",
"ownerRange", "ownerRangeOutside", "rangeGrid", "upgradeNum", "bonds")
self._views = {}
for kind, table in (("chess", "chess"), ("item", "items"), ("token", "tokens"), ("band", "bands")):
Expand Down Expand Up @@ -135,8 +146,8 @@ def _record(self, kind, identifier):
row = self._views.get(kind, {}).get(identifier)
if not isinstance(row, dict):
raise UnsupportedPublicState(f"Unknown public {kind} identity: {identifier!r}")
if kind == "chess" and row.get("isDiy"):
raise UnsupportedPublicState("Custom DIY records require a separate catalog contract")
if kind == "chess" and row.get("isDiy") and row.get("diyFor") not in self._data.get("diy", {}):
raise UnsupportedPublicState("DIY identity has no resolved operator configuration")
return row

def validate_identity(self, kind, identifier):
Expand Down Expand Up @@ -246,7 +257,9 @@ def validate_state(self, state):
or public.get("modeId") not in self._data["config"]["modes"]
or public.get("modeId") != "mode_single_" + public["difficulty"].lower()):
raise UnsupportedPublicState("Plugins/custom modes are outside this vanilla catalog")
for name in ("diy", "loadout", "ops"):
if own.get("diy") != self._data.get("diy", {}):
raise UnsupportedPublicState("DIY configuration differs from the resolved public catalog")
for name in ("loadout", "ops"):
if own.get(name) != {}:
raise UnsupportedPublicState(f"Nondefault or unknown {name} is unsupported")
if own.get("standIns") != []:
Expand Down
8 changes: 7 additions & 1 deletion arkguardrl/decision_session.py
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,8 @@ def reset(self, **kwargs):
def decision(self):
if self.result is None:
raise RuntimeError("Reset before constructing a decision")
return build_decision(self.result.observation, self.catalog, self.history)
return build_decision(self.result.observation, self.catalog, self.history,
encoder=getattr(self.environment, 'numeric_encoder', None))

def step(self, action):
if self.result is None:
Expand All @@ -50,4 +51,9 @@ def step(self, action):
def observation_features(self):
if self.result is None:
raise RuntimeError("Reset before encoding a successor")
encoder = getattr(self.environment, 'numeric_encoder', None)
if encoder is not None:
state = self.result.observation
self.catalog.validate_state(state)
return encoder(state, (), self.catalog, self.history.snapshot(state))[0]
return encode_observation(self.result.observation, self.catalog, self.history)
8 changes: 6 additions & 2 deletions arkguardrl_core/env_actions.py
Original file line number Diff line number Diff line change
Expand Up @@ -5,11 +5,15 @@


def piece_actions(state, catalog, context, *, recovery):
return kernel().prep_piece_actions(*piece_inputs(state, catalog, context, recovery=recovery))


def piece_inputs(state, catalog, context, *, recovery):
from arkguardrl.candidates import empty_deployment_allowed

own = state['own']
if recovery and own['canReady']:
return []
return ([], 0, own['deployCount'] >= own['deployCap'], recovery, True)
locations, _, cells = context
terrain = {'all': 0, 'melee': 0, 'high': 0}
for (row, col), kind in cells.items():
Expand Down Expand Up @@ -40,5 +44,5 @@ def piece_actions(state, catalog, context, *, recovery):
pieces.append((uid, {'board': 0, 'hand': 1, 'temp': 2}[area], kind,
cell, direction, mask, [item['uid'] for item in piece['items']]))
empty_hand = sum(1 << i for i, piece in enumerate(own['hand']) if piece is None)
return kernel().prep_piece_actions(pieces, empty_hand,
return (pieces, empty_hand,
own['deployCount'] >= own['deployCap'], recovery, own['canReady'])
Loading
Loading