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
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 32 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -71,6 +71,38 @@ Linux 动态库为 `lib_native.so`,Windows 使用 CI 的 `_native*.pyd`。[跨
- 自然结束为 `terminated`,预算耗尽为 `truncated`,原因见 `info["reason"]`。相同种子可复现,`reset(seed=None)` 延续 RNG 流。
- Gym 支持 Sync/Async,Rust slots 支持 1–64 个环境及局部重置。Async `spawn` 入口使用 `if __name__ == "__main__"`。

### 逐决策公开反馈

NativeSolo 和 NativeBatch 的 decision ledger JSON 现在包含独立的 `feedback` 字段。
`NativeLedgerEnv.feedback` 和 Rust slots 的 `info["feedback"]` 返回该侧带记录。
重置时为 `null`,每次决策替换为 `arkguard.decision-feedback.v1`,包含
`decisionRevision`、`resultRevision` 和按 transport revision 排列的 `receipts`。
每个 receipt 使用 `arkguard.public-feedback.v1`,携带 `revision`、`battle`、`economy`。
反馈由动作及后续自动战斗共同生成,初始设置授予发生在首个决策之前。

`battle` 在战斗结算时包含 1 起算 `round`、`units`、`complete`、`partial`、
`droppedUnits`、`missingMetrics`。每行有局内 `battleUnitId`、准备阶段 `sourceUid`、
召唤者 `ownerSourceUid`、`ownerAttributionComplete`、`kind`,以及真实累计的
`damage`、`healing`、`taken`、`attacks`、`kills`。
`damage` 是异阵营归属伤害,`taken` 是实际 HP 损失,`healing` 是有效治疗量,
`attacks` 使用现有攻击事件计数,`kills` 使用 `deployment.kills` 的直接击杀归属。
直接击杀计数与出怪 ledger 的 `creditedKills` 有各自口径,召唤物单列,调用方可按
`ownerSourceUid` 汇总。准备棋子 UID 缺失或召唤者已释放时对应值为 `null`,
归属缺失独立标记。最多保留 4096 条已移除盟友的最终统计,另加入结算时仍在
注册表中的盟友(受现有 unit 容量约束)。移除记录超出后 `droppedUnits > 0`、
`partial=true`。完整性描述计数保留情况,技能实现覆盖另行判断。
当前接口未提供阻挡次数和阻挡时长。

`economy.events` 包含 1 起算 `round` 和 `sourceBond`、`effect`。
`miraShip`/`visiShip` 的层数返金报告实际 `amount` 和入账 `destination`
(`funds` 或 `pendingFunds`),`miraShip` 免费刷新报告已授予次数。
`investShip` 报告额外驻守调用的 `sourceUid`、`garrisonId`、1 起算 `invocation`,
以及实际 `fundsDelta`、`pendingFundsDelta`、`freeRefreshesDelta`。
该增量包含调用内嵌套效果,返金事件可能同时描述其中的入账,消费方须避免重复累计。
物品和层数等非货币结果尚缺归属,故 invest 事件 `complete=false`。
经济总对象始终标 `complete=false`、`partial=true`,用 `coverage`/`missing` 列明范围。
单次累积最多保留 4096 个经济事件,截断数见 `droppedEvents`。

## 性能

![同种子同动作购买部署对局,Rust 相对 Node 在三个核心上为 1.32–1.36 倍](docs/assets/benchmark-throughput.svg)
Expand Down
46 changes: 46 additions & 0 deletions crates/engine/src/battle/health.rs
Original file line number Diff line number Diff line change
Expand Up @@ -167,6 +167,8 @@ pub struct World {
deployment_sequence: u64,
attack_sequence: u64,
units: BTreeMap<Id, Unit>,
retired_ally_feedback: Vec<serde_json::Value>,
dropped_ally_feedback: u64,
pools: BTreeMap<Id, StoredPool>,
players: BTreeMap<Id, PlayerTotals>,
capacities: [usize; 3],
Expand Down Expand Up @@ -233,6 +235,8 @@ impl World {
deployment_sequence: 0,
attack_sequence: 0,
units: BTreeMap::new(),
retired_ally_feedback: Vec::new(),
dropped_ally_feedback: 0,
pools: BTreeMap::new(),
players: BTreeMap::new(),
capacities: [unit_capacity, pool_capacity, player_capacity],
Expand Down Expand Up @@ -290,10 +294,52 @@ impl World {
if !u.removed || u.pins > 0 || u.blocked_by.is_some() || !u.blocking.is_empty() {
return Err("Cannot release a retained or still linked unit".into());
}
if u.side == Side::Ally {
if self.retired_ally_feedback.len() < 4096 {
let feedback = self.ally_feedback(id)?;
self.retired_ally_feedback.push(feedback);
} else {
self.dropped_ally_feedback += 1;
}
}
super::enemy::clear(self, id)?;
self.units.remove(&id);
Ok(())
}
fn ally_feedback(&self, id: Id) -> Result<serde_json::Value, String> {
let u = self.unit(id)?;
let source = u.summoner;
let owner_uid = source.and_then(|owner| self.unit(owner).ok()?.deployment.uid);
Ok(serde_json::json!({
"battleUnitId": id, "sourceUid": u.deployment.uid,
"ownerSourceUid": owner_uid,
"ownerAttributionComplete": source.is_none() || owner_uid.is_some(),
"kind": match u.deployment.kind {
super::deploy::Kind::Operator => "operator",
super::deploy::Kind::Token => "token",
super::deploy::Kind::Device => "device",
super::deploy::Kind::Enemy => "enemy",
},
"damage": u.damage_dealt, "healing": u.healing_done,
"taken": u.damage_taken, "attacks": u.attacks,
"kills": u.deployment.kills,
}))
}
/// Public measured contributions, including permanently removed allies.
pub(crate) fn contribution_feedback(&self) -> Result<serde_json::Value, String> {
let mut units = self.retired_ally_feedback.clone();
for (&id, u) in &self.units {
if u.side == Side::Ally {
units.push(self.ally_feedback(id)?);
}
}
Ok(serde_json::json!({
"complete": self.dropped_ally_feedback == 0,
"partial": self.dropped_ally_feedback != 0,
"droppedUnits": self.dropped_ally_feedback,
"missingMetrics": [], "units": units,
}))
}
pub fn pool(&self, id: Id) -> Option<&Pool> {
self.pools.get(&id).map(|p| &p.value)
}
Expand Down
8 changes: 8 additions & 0 deletions crates/engine/src/battle/runtime.rs
Original file line number Diff line number Diff line change
Expand Up @@ -814,6 +814,14 @@ impl Field {
}
/// Owned accounting snapshot. This internal field result is not a policy
/// observation and exposes no provisional success for a faulted execution.
/// Settled public event counters only, separate from policy observations.
pub fn contribution_feedback(&self) -> Result<Value, String> {
self.healthy()?;
if !self.finished() {
return Err("Contribution feedback requires completed combat".into());
}
self.core.world.contribution_feedback()
}
pub fn result(&self) -> Result<FieldResult, String> {
self.healthy()?;
if !self.finished() {
Expand Down
24 changes: 24 additions & 0 deletions crates/engine/src/solo.rs
Original file line number Diff line number Diff line change
Expand Up @@ -141,6 +141,7 @@ pub struct Runner {
rounds_passed: u32,
limits: Limits,
last_result: Option<FieldResult>,
battle_feedback: Option<Value>,
prep: Option<preparation::Preparation>,
map: crate::battle::runtime::MapConfig,
draft: Option<draft::Flow>,
Expand Down Expand Up @@ -294,6 +295,7 @@ impl Runner {
rounds_passed: 0,
limits,
last_result: None,
battle_feedback: None,
prep: None,
map: Default::default(),
draft: None,
Expand Down Expand Up @@ -715,6 +717,12 @@ impl Runner {
Ok(value) => value,
Err(error) => return self.fail(error),
};
let mut feedback = match field.contribution_feedback() {
Ok(value) => value,
Err(error) => return self.fail(error),
};
feedback["round"] = json!(self.index + 1);
self.battle_feedback = Some(feedback);
let gains = field.layer_gains();
if let Err(error) = self.settle(result, layers, &gains) {
return self.fail(error);
Expand Down Expand Up @@ -744,6 +752,22 @@ impl Runner {
None
})
}
pub(in crate::solo) fn take_feedback(&mut self) -> Value {
let economy = self
.prep
.as_mut()
.map(|prep| {
json!({"events": std::mem::take(&mut prep.economy_feedback),
"droppedEvents": std::mem::take(&mut prep.dropped_economy_feedback),
"coverage": ["miraShip.freeRefresh", "miraShip.funds", "visiShip.funds",
"investShip.extraGarrisonInvocation"],
"complete": false, "partial": true,
"missing": ["otherEconomicEffects", "investShip.nonCurrencyOutcomes"]})
})
.unwrap_or(Value::Null);
json!({"schema": "arkguard.public-feedback.v1",
"battle": self.battle_feedback.take(), "economy": economy})
}
pub fn last_result(&self) -> Result<Option<FieldResult>, String> {
self.healthy()?;
Ok(self.last_result)
Expand Down
12 changes: 12 additions & 0 deletions crates/engine/src/solo/preparation.rs
Original file line number Diff line number Diff line change
Expand Up @@ -187,6 +187,8 @@ pub(super) struct Preparation {
bounties: Vec<bounties::Bounty>,
meta: Option<Meta>,
free_refreshes: u64,
pub(in crate::solo) economy_feedback: Vec<Value>,
pub(in crate::solo) dropped_economy_feedback: u64,
grid: Arc<DeployMap>,
boss: bool,
deploy_cap: usize,
Expand Down Expand Up @@ -286,6 +288,8 @@ impl Preparation {
rules,
meta,
free_refreshes: 0,
economy_feedback: Vec::new(),
dropped_economy_feedback: 0,
grid: Arc::new(grid),
boss,
deploy_cap,
Expand Down Expand Up @@ -316,6 +320,14 @@ impl Preparation {
}
Ok(prep)
}
fn record_economy_feedback(&mut self, mut event: Value) {
event["round"] = json!(self.meta.as_ref().map(|meta| meta.round));
if self.economy_feedback.len() < 4096 {
self.economy_feedback.push(event);
} else {
self.dropped_economy_feedback += 1;
}
}
pub fn begin_round(
&mut self,
round: u32,
Expand Down
4 changes: 4 additions & 0 deletions crates/engine/src/solo/preparation/effects.rs
Original file line number Diff line number Diff line change
Expand Up @@ -863,6 +863,10 @@ impl Preparation {
.earn(gain.trunc() as u64)
.map_err(|_| Error::Capacity)?;
}
self.record_economy_feedback(json!({"sourceBond": id,
"effect": "bond_layer_gain_coin", "amount": gain.trunc() as u64,
"destination": if pending { "pendingFunds" } else { "funds" },
"complete": true}));
}
}
if id == "visiShip" {
Expand Down
18 changes: 17 additions & 1 deletion crates/engine/src/solo/preparation/effects/dispatch.rs
Original file line number Diff line number Diff line change
Expand Up @@ -176,8 +176,21 @@ impl Preparation {
}
}
}
for _ in 0..self.gain_repeat(hook)? {
for invocation in 0..self.gain_repeat(hook)? {
let before = (player.funds, player.pending, self.free_refreshes);
self.run_rule(&rule, &call, player)?;
if invocation > 0 {
self.record_economy_feedback(json!({
"sourceBond": "investShip", "effect": "extraGarrisonInvocation",
"sourceUid": call.piece.uid, "garrisonId": id,
"invocation": invocation + 1,
"fundsDelta": player.funds as i64 - before.0 as i64,
"pendingFundsDelta": player.pending as i64 - before.1 as i64,
"freeRefreshesDelta": self.free_refreshes as i64 - before.2 as i64,
"complete": false,
"missing": ["nonCurrencyOutcomes"],
}));
}
}
}
Ok(())
Expand Down Expand Up @@ -352,6 +365,9 @@ impl Preparation {
if self.meta.as_mut().unwrap().rng.next_f64() < chance {
self.free_refreshes =
add(self.free_refreshes, 1).map_err(|_| Error::Capacity)?;
self.record_economy_feedback(json!({"sourceBond": "miraShip",
"effect": "bond_refresh_shop_next_free", "amount": 1,
"destination": "freeRefreshes", "complete": true}));
}
}
}
Expand Down
22 changes: 18 additions & 4 deletions crates/engine/src/solo/session.rs
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,9 @@ impl Session {
session.public_setup = public_setup;
Ok(session)
}
pub(in crate::solo) fn from_runner(run: Runner) -> Self {
pub(in crate::solo) fn from_runner(mut run: Runner) -> Self {
// Setup grants precede the first decision and are not action outcomes.
run.take_feedback();
Self {
run,
revision: 0,
Expand Down Expand Up @@ -122,6 +124,18 @@ impl Session {
"accepted": accepted, "rejection": rejection, "ticks": ticks,
}))
}
fn feedback_receipt(
&mut self,
accepted: Option<bool>,
rejection: Option<&str>,
ticks: usize,
) -> Result<Value, String> {
let mut receipt = self.receipt(accepted, rejection, ticks)?;
let mut feedback = self.run.take_feedback();
feedback["revision"] = json!(self.revision);
receipt["feedback"] = feedback;
Ok(receipt)
}
pub fn status(&self) -> Result<Value, String> {
self.healthy()?;
self.receipt(None, None, 0)
Expand Down Expand Up @@ -161,7 +175,7 @@ impl Session {
match result {
Err(error) if self.run.phase() != Phase::Faulted && is_rejection(&error) => {
self.revision += 1;
self.receipt(Some(false), Some(&error), 0)
self.feedback_receipt(Some(false), Some(&error), 0)
}
Err(error) => self.fail(error),
Ok(()) => {
Expand All @@ -170,7 +184,7 @@ impl Session {
Ok(a) => a,
Err(error) => return self.fail(error),
};
self.receipt(Some(true), None, advance.ticks)
self.feedback_receipt(Some(true), None, advance.ticks)
}
}
}
Expand All @@ -185,7 +199,7 @@ impl Session {
Err(error) => return self.fail(error),
};
self.revision += 1;
self.receipt(None, None, advance.ticks)
self.feedback_receipt(None, None, advance.ticks)
}
}
fn is_rejection(error: &str) -> bool {
Expand Down
9 changes: 9 additions & 0 deletions crates/python/src/ledger.rs
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@ pub struct DecisionLedger {
pub blocked: BTreeSet<String>,
progress: PublicProgress,
reward: NativeProgressCore,
feedback: Value,
}

impl DecisionLedger {
Expand All @@ -31,6 +32,7 @@ impl DecisionLedger {
blocked: BTreeSet::new(),
progress,
reward,
feedback: Value::Null,
})
}

Expand All @@ -45,6 +47,7 @@ impl DecisionLedger {
#[derive(serde::Serialize)]
struct Snapshot<'a> {
observation: &'a Value,
feedback: &'a Value,
history: &'a Value,
blocked: &'a BTreeSet<String>,
execution: Option<Value>,
Expand All @@ -53,6 +56,7 @@ impl DecisionLedger {
}
serde_json::to_string(&Snapshot {
observation: &self.state,
feedback: &self.feedback,
history: &self.policy_history,
blocked: &self.blocked,
execution,
Expand All @@ -72,6 +76,7 @@ impl DecisionLedger {
let before = Arc::clone(&self.state);
// Preserve the immediate receipt before advancing the resulting battle.
let mut transport = session.step(action, 0)?;
let mut receipts = vec![transport["feedback"].clone()];
let accepted = transport["accepted"]
.as_bool()
.ok_or("Missing action acceptance")?;
Expand All @@ -91,6 +96,7 @@ impl DecisionLedger {
return Err("Combat budget exhausted before a decision boundary".into());
}
transport = session.advance(tick_budget)?;
receipts.push(transport["feedback"].clone());
advances += 1;
if transport["budgetExhausted"] != true {
after = Arc::new(session.observation()?);
Expand All @@ -107,6 +113,9 @@ impl DecisionLedger {
accepted,
)?;
let reward = self.reward.step(&before, &after)?;
self.feedback = json!({"schema": "arkguard.decision-feedback.v1",
"decisionRevision": before["revision"], "resultRevision": after["revision"],
"receipts": receipts});
self.state = after;
self.snapshot(Some(execution), Some(reward), advances)
}
Expand Down
3 changes: 2 additions & 1 deletion src/arkguardrl_core/native_batch.py
Original file line number Diff line number Diff line change
Expand Up @@ -98,7 +98,8 @@ def _refresh(self, slot):
slot.decision = None
slot.info = dict(candidate_count=0,
phase=slot.state['phase'], round=slot.state['round'],
engine_seed=slot.engine_seed, reason=slot.reason or '')
engine_seed=slot.engine_seed, reason=slot.reason or '',
feedback=deepcopy(slot._ledger.get('feedback')))

def _output(self):
n, k = self.num_envs, self.max_candidates
Expand Down
5 changes: 5 additions & 0 deletions src/arkguardrl_core/native_ledger.py
Original file line number Diff line number Diff line change
Expand Up @@ -130,6 +130,11 @@ def _encode_numeric(self, state, actions, catalog, history):
raise ValueError('Numeric encoding requires the current public snapshot and catalog')
return encode(self.session, state, actions, history, native_history=True)

@property
def feedback(self):
"""Public measured outcomes from the most recent native decision."""
return deepcopy(getattr(self, '_ledger', {}).get('feedback'))

def _consume(self, raw):
ledger = json.loads(raw)
state = ledger['observation']
Expand Down
Loading