diff --git a/design/engineering/architecture/architecture.md b/design/engineering/architecture/architecture.md index 7b71b09c..005cdb3c 100644 --- a/design/engineering/architecture/architecture.md +++ b/design/engineering/architecture/architecture.md @@ -2,8 +2,8 @@ ## 文档状态 -- 版本:1.15 -- 最近更新:2026-10-26(通信形态选型理由、效果引擎定位、架构原则 9 停点机制补文+已落定未决项、过时陈述与冻结计数清扫) +- 版本:1.16 +- 最近更新:2026-10-26(AdventureRunner 真拆分设计定稿——核心层三新件行(HeroLedger/AttuneLoadout/CurioStop)+「冒险域拆分定稿」节) - 引擎:Godot 4.7.2-stable(GDScript 单语言;2026-09-07 锁定) - 评审模式:solo(`review-mode.txt`,2026-09-12 用户拍板——TD/LP 门禁按 solo 跳过,用户授权架构产出自主推进、迭代期回调) - 覆盖 GDD:现行全集(根索引=`design/gdd/02-系统清单.md`,文档树构成以根索引为准) @@ -105,6 +105,9 @@ | **helper_items**(A5,切片已实装秘宝域) | HelperItemTable、探测显影语义 | (契约规范源:`../../gdd/systems/跨局循环/秘宝.md`——桥接位:A2 查询接口 + A4 counter_item_ids) | A2 / A4 / B4 | 无 | | **CurioDeck**(`core/curio_deck.gd`,A5 秘宝域令牌池件,迭代 37 自 AdventureRunner 拆出) | 三选一/商店共享池的持久多重集、抽签(候选抽取)、cap 库存与专长凭证三计数与判定唯一所有者——件只管池与判定,停点编排与兑付推进留冒险编排器 | `draw_candidates(channel)` 抽签;`consume_deck_token` / `consume_pool_purchase` 池消耗;`cap_ok` 上限判定;`feat_ticket_consider` 凭证判定;`stock_snapshot` / `pool_stock` 只读投影;宿主兑付单点经 `bind_handlers` 注入方法 Callable(选中摘牌后的加算区/账本落点仍在宿主) | ConfigDB(秘宝令牌行集);注入 RngServiceCore(reward_pick 封闭流,禁自建随机) | 无(RefCounted 纯逻辑) | | **ShopSession**(`core/shop_session.gd`,商店会话件,迭代 37 自 LevelRunner 拆出) | 关卡商店双模式(legacy 固定三件加定价/pool 共享令牌池)的货架、定价、购买与刷新唯一宿主——账本/钱包/装配集归宿主 LevelRunner(共享引用经 `bind` 注入,出账直接落同一引用改写宿主账本);legacy 模式零 RNG 零池消费(off 对照承载) | 货架与定价只读面(`shop_products` / `shop_shelf` / `current_price` / `shop_refresh_cost`)+写入口(`buy_product` / `buy_pool_item` / `shop_refresh` / `player_request_refresh` / `open_pool`);外部调用面由 LevelRunner 同签名委托承载(外部零变化) | ConfigDB(商店行集);注入 RngServiceCore;宿主钱包/账本引用;pool 模式令牌消耗与判定经注入 Callable 转 CurioDeck | 无 | +| **HeroLedger**(`core/hero_ledger.gd`,冒险域主角实体账,2026-10-26 真拆分批设计定稿——实现批建件) | 冒险生命周期主角数值与获得记录唯一所有者:生命与 GP 钱包(gain/spend/clear 单写原语,钱包事件发射点归件)、锻造强化快照、调试百分比、攻击/甲类型轴快照、特性持有集(活引用注入——关内兑付当关生效)、本局钥石增量与逐杀明细、真视使用记录;获得记录三层结构=获得记录列表(三选一件/商店购买/战末奖励各一条)→属性增益明细(带来源指回)→四轴汇总(由明细推导);生效上限与回血封顶公式单点归件 | 构造注入;单写原语族+只读投影;断点自交片段(账本键+获得日记键) | ConfigDB(表值读取);由 AdventureRunner 冒险开始创建、注入 CurioStop/level_runner/ShopSession/战斗 encounter | 无(RefCounted 纯逻辑) | +| **AttuneLoadout**(`core/attune_loadout.gd`,同调配装件,2026-10-26 真拆分批设计定稿——实现批建件) | 装备中的秘宝件对象集唯一所有者(每件内含充能单位与重置周期);同调充能的物化行为唯一事实源——种行/补行改写时同步(RunLedger 充能字典轨与差额对账函数退役);旧档 aux_items 同调行迁移归件 | 构造注入;充能查询/消耗/按周期重置原语;断点自交片段(attunement_charges 键,键名与策略不变) | ConfigDB(秘宝行集);TreasureItems(同调行投放面);注入战斗使用路径 | 无 | +| **CurioStop**(`core/curio_stop.gd`,三选一停点件,2026-10-26 真拆分批设计定稿——实现批建件) | 三选一停点编排唯一所有者(架构原则 9 本域承载):停点三态(关卡完成三选一在途/已兑付待推进/奖励节点三选一在途)、刷新三源账(刷新件 X/营地池 Y/刷新券存量/付费刷新计数)、兑付方法族(pick/refresh/redeem/skip)、凭证出箱(RAP/时沙待注入);三选一信号面自带;零自动推进停点语义承载 | 对外=开停点/刷新/兑付/放行谓词/交断点片段五组入口+信号面(curio_choice_presented/curio_resolved);由 AdventureRunner 关卡完成受理时调用 | ConfigDB;注入 CurioDeck(抽签/摘牌)与 HeroLedger(落账);随机只经 CurioDeck 的 reward_pick 封闭流 | 无 | ### 功能层 @@ -123,6 +126,17 @@ - **结算五段**:B1 编排器的每轮结算序列拆为 `game/core/settlement/` 五个段类——GrantSegment(①授予段,含封印判定与 counter/grant 助手单点)→ AuraSegment(②增益/减益段)→ CombatSegment(③战斗段)→ DecaySegment(④衰减段)→ VerdictSegment(⑤判定段,返回裁定,终局早退语义留 B1)。段序骨架冻结于 `SettlementTable.segment_order` 语义,B1 退为段序编排+接线;段类可直接 `new()` 单测(`settle_segments_test` 在役)。 - **RunLedger 四账**:`game/core/run_ledger.gd` 单类持四本共享账——同调充能账/真视使用计数/冒险域计数器/统一冒险加算区。所有权:AdventureRunner 开局构造、全程唯一宿主;LevelRunner 经 `set_run_ledger` 下传装配 encounter;战斗侧(B1)经 `encounter["ledger"]` 拿引用、只走 read/append 原语族。审计 P1-4「共享可变字典跨三层三处可写」由「函数签名上不可见的共享引用」换成签名可见的显式类。冒险桶计数器无导出/灌入时点:EffectContext 持 `run_ledger.adventure_counters` 的同一字典引用,引擎静态计数口就地直写,跨战持久随 RunLedger 生灭(2026-10-21 迭代 32 卡②无状态化写入)。 +### 冒险域拆分定稿(2026-10-26 用户裁写入——AdventureRunner 真拆分设计闭合;实现批完成后本节改写为现状登记) + +- **应用层形态**:adventure_runner 退出上帝对象、转薄应用层(DDD 应用层形态)——只留冒险状态机、关序推进、结算受理、建件接线、效果引擎冒险桶字典持有(桶=效果引擎域数据,应用层只锚定生命周期);零领域决策。核心层表三新件行(HeroLedger/AttuneLoadout/CurioStop)即本拆分目标。 +- **CurioDeck 转纯池**:bind_handlers 反向回调退役;商店购买消费经注入 Callable 链至 CurioStop 兑付单点——牌库只管抽签/消耗/cap 判定/凭证计数。 +- **RunLedger 退役**:四账各归其主——加算区/购买记录/钥石增量/特性集/真视记录归 HeroLedger,充能归 AttuneLoadout,冒险桶字典归应用层持有;战斗侧 encounter 注入面由单一账类引用改为多路(桶字典+实体账+配装件);ShopSession 账本引用面同步换代,商店属性商品加算改经 HeroLedger 单写原语。 +- **level_runner**:依赖改构造注入一次给齐(后置 setter 群与商店重绑机制退役;注入活引用禁快照——特性集共享引用语义保留);商店白盒转发属性撤除;战斗→关卡信号转发族保留(战斗实例每节点新建,关卡层做战斗域稳定面)。 +- **断点片段化**:各件自写自读自己的键(关卡层交关卡域五键片段:node_id/visited_ids/aux_items/shop_shelf/shop_visit_buys),缺键回退策略随领域知识归各件;应用层唯一落盘口(收齐各件片段拼成顶层快照后写盘),写触发点不变(五处);既有 27 键逐键冻结;新增获得日记键沿扩列不升版先例——旧档缺日记回退汇总键直载并跳过比对,日记在档时由日记推导汇总、与留存值不符即报错中止(迁移正确性自检)。 +- **信号直连**:adventure_runner 六转发信号族(node_entered/choices_presented/step_row/round_started/board_changed/wallet_changed)退役;呈现层在 level_started 重取点重订阅关卡对象信号(旧实例连接随引用释放消亡);「关卡开始信号前零发射」契约写进关卡件头注;「恰好连接一次」断言用 is_connected 守卫(release 模板剥 assert);三选一信号面归 CurioStop。 +- **调用直连**:不留中间人委托壳(纯转传=Middle Man 反模式,2026-10-26 用户裁定);呈现控制器经取值回调持件——回调只许捕获长活根对象,禁件方法 Callable(防悬挂);约 30 个调用文件改址;测试/探针直连件读写。 +- **验收红线**:游戏行为零变化(RNG 流名 reward_pick 与消费序零漂移、信号顺序契约冻结、同种子逐位一致);gdstyle 基线禁改(类变量计数下降属改善);怪物寻址 resolve_enemy_rowset 调用面与关卡参数档装配零变化(未来关卡主题的数据缝不堵)。 + ### 呈现层 | 模块 | 独占职责 | 对外暴露 | 消费依赖 | 引擎 API | diff --git a/待办清单.md b/待办清单.md index e094f6bc..f809b1d2 100644 --- a/待办清单.md +++ b/待办清单.md @@ -25,12 +25,19 @@ - 验收面预案要点(迭代 37 批内成文,写卡输入):每新件至少一条真实入口断言(RewardStop 走 start_adventure→关卡完成三选一→选件→断言加算区/池余量/停点态清零;HeroLedger 的 rest 与 heal 封顶走真链;BreakpointSchema 承〔wr2〕三条+ui_click_probe wc2 续玩真链);撤销证明逐单元「回退本批 hunk→断言红→还原复绿」、禁注入式变异;断点 27 键键名/缺省/回退策略逐键冻结;RNG 流名(reward_pick)与消费序零漂移;`tools/gdstyle_baseline.txt` 禁改、计数下降属改善不判红;MC 与基线数据逐项比对是否发起由用户裁(触及存档/RNG/结算面)。 - 目标切法(待裁,非结论;各件收编范围=迭代 37 批内按变化原因划界的成文要点):AdventureFlow(留名 adventure_runner;收 state/level_index/levels_total/_runner/_pending_next_level/_last_level_payload 与 start/resume/关序推进/结算受理方法族=状态机+关序推进+结算受理一次)/RewardStop(收停点三态 _curio_pending/_curio_result/_node_curio_pending、刷新双源 _attune_refresh_x/_refresh_stock 与 pick_curio/refresh 族/兑付推进方法族)/CurioDeck(已在册:池与凭证计数已入件)/HeroLedger(收 ledger/run_ledger/_base_override/_override/purchased/keystone/_feats 与 effective_max_hp/apply_rest 等=数值叠加与生命口径)/BreakpointSchema(收 BREAKPOINT_FIELDS 27 键登记的派生段与 _snapshot_breakpoint/_bp_read/`_resume_*` 六小函数=存档格式);呈现转名(`_forward_*` 六件+信号面)下沉装配层。判据=件拥有状态与决策、宿主不留同名数据槽、件→宿主只传值不回调宿主私有族。 - 相关文档:design/engineering/architecture/architecture.md(模块归属表须随拆分登记新件)· design/gdd/systems/表现与支撑/存档序列化.md(断点域契约,27 键冻结面)· 迭代 37 卡④ 契约 1 冻结公开面(commit e5ee4d04),正是本条无法在批内完成的原因(需求卡片已退役,口径见 git 历史) - -**缺口**:拆分边界未裁四件——①RewardStop 与 CurioDeck 的分界(停点态 `_curio_pending`/`_curio_result`/`_node_curio_pending` 归谁、凭证兑付 `_redeem_feat_ticket` 在哪侧);②HeroLedger 与既有 RunLedger 的关系(合并还是分层,RunLedger 已被 LevelRunner 共享引用);③断点 schema 是否独立成件(卡④ §11 以「27 键多数取宿主态、开洞面>收益」淘汰过独立件,真拆分后该论据失效,需重裁);④公开面收缩后 main.gd/camp_shop_presenter/curio_interact_controller 与三处测试直引点的改法与验收面;⑤board_view 13 条同类装置撤除时探针面与组合根直读面的改法(terrain_tile_sets_test/ui_contrast_probe/ui_input_probe 直引在案)。裁完才进写卡段。 +- **2026-10-26 文档设计已闭合**:设计讨论全套裁定(应用层薄编排/停点件 CurioStop/角色实体账 HeroLedger 三层获得结构/同调配装件 AttuneLoadout 充能单源化/断点片段化+获得日记键扩列/信号直连/构造注入/调用方直连不留壳)经 godot-master 技能库独立子代理审查修正后定稿——三高危修正(充能改单源化:物化行为唯一事实源;日记比对旧档豁免:缺日记回退汇总键直载;ShopSession 补入改造面:商店加算写通道经实体账单写原语)均已并入。定稿登记=design/engineering/architecture/architecture.md v1.16(核心层三新件行+「冒险域拆分定稿」节);钥石入账维持收束入账(获取即入账曾议、用户裁维持现状——中途入账有断点写盘非原子致账目撕裂的风险);获得明细随档保存(日记为正主、汇总键留作旧档兼容载入与一致性校验) **改动面**:游戏代码 -**状态**:待文档设计 +**状态**:文档设计已闭合+待写卡 + +#### level_runner 商店委托层拆除——迭代 37 冻结契约期过渡件(2026-10-26 登记,来源=批次移交) + +**实况**:证据=迭代 37 卡④ ShopSession 拆分时立「冻结公开面」契约,level_runner 保留 buy_product/shop_refresh 等同签名委托方法(架构模块表登记为「外部调用面由宿主同签名委托承载」)。2026-10-26 AdventureRunner 真拆分设计会话裁定新原则:纯转传委托=Middle Man 反模式,新件一律调用方直连不留壳(godot-master 技能库审查同判);本批不动该委托层(真拆分条目范围仅撤 8 条白盒转发属性),其拆除与调用文件改址由本条承接。 + +**改动面**:游戏代码 + +**状态**:待写卡 #### 超预算图策略升级路径——等比缩放与滚动视口两案待裁(2026-10-24 登记,来源=批次移交)