文档更新
This commit is contained in:
jkboy
parent
dd829f599b
commit
60b415039c
@ -30,9 +30,10 @@
|
||||
### 核心职责 (Responsibilities)
|
||||
* **流程决策:** 根据用户输入（来自主菜单 UI），决定启动“新游戏”流程还是“载入存档”流程。
|
||||
* **数据准备:**
|
||||
* **新游戏:** 确保 `InitialDataManager` 数据加载完成 -> 调用 `InitialDataManager` 获取初始数据 (`settings_data`, `task_dev_data`) -> **调用 `_build_initial_state` 方法，根据获取的数据构建注入 `GameState` 的初始状态字典。此方法会：**
|
||||
* **新游戏:** 确保 `InitialDataManager` 数据加载完成 -> 调用 `InitialDataManager` 获取初始数据 (`settings_data`, `task_dev_data`, `npc_initial_data`) -> **调用 `_build_initial_state` 方法，根据获取的数据构建注入 `GameState` 的初始状态字典。此方法会：**
|
||||
* **合并基础设置 (`Init_Base.json`) 到状态字典的顶层。**
|
||||
* **处理任务开发相关数据 (`task_development.json`)，提取其中需要动态追踪的状态（如平台的 `enabled`, `Market_share`；玩法/主题的 `enabled`, `Experience`；策略的 `enabled`；产品侧重点的完整结构），并将这些动态状态组织在一个名为 `"task_development"` 的子字典内，再将该子字典存入主状态字典。**
|
||||
* **处理 NPC 数据 (`npc.json`)，将从 `npc_initial_data` 中获取的 NPC 定义（通常是 `npc_defs["npc"]` 部分）存入主状态字典的 `"npcs"` 键下。**
|
||||
* **载入存档:** **接收**由外部（例如存档选择 UI，它会调用 `SaveLoadManager.load_game`）加载并传入的存档数据字典。
|
||||
* **数据注入:**
|
||||
* **新游戏:** 将构建好的初始状态字典传递给 `GameState.initialize_for_new_game()`。
|
||||
@ -51,12 +52,12 @@
|
||||
|
||||
### 交互关键点 (Key Interactions)
|
||||
* **接收:** 来自 UI 的调用 (`start_new_game_process`, `load_game_process`)。
|
||||
* **调用:** `InitialDataManager` (在新游戏流程中调用 `ensure_data_loaded`, `get_starting_settings`, `get_task_development_data`), `GameState` (调用 `initialize_for_new_game` 或 `restore_state`)。
|
||||
* **调用:** `InitialDataManager` (在新游戏流程中调用 `ensure_data_loaded`, `get_starting_settings`, `get_task_development_data`, `get_npc_initial_data`), `GameState` (调用 `initialize_for_new_game` 或 `restore_state`)。
|
||||
* **发出:** `new_game_initialized`, `game_loaded` 信号。
|
||||
* **(可能)** `SceneTree` (用于切换场景，虽然未在提供的代码片段中直接显示，但通常是其职责一部分)。
|
||||
|
||||
### 核心逻辑流程 (Core Logic/Flow)
|
||||
* **新游戏:** (UI 调用 `start_new_game_process`) -> 显示加载 -> 确保 `InitialDataManager` 就绪 -> 获取初始数据 (`settings`, `task_dev`) -> **调用 `_build_initial_state` 构建包含 `"task_development"` 子结构的初始状态字典** -> 调用 `GameState.initialize_for_new_game()` -> 发出 `new_game_initialized` 信号 -> (后续逻辑) 切换场景 -> 隐藏加载。
|
||||
* **新游戏:** (UI 调用 `start_new_game_process`) -> 显示加载 -> 确保 `InitialDataManager` 就绪 -> 获取初始数据 (`settings`, `task_dev`, `npc_initial_data`) -> **调用 `_build_initial_state` 构建包含 `"task_development"` 和 `"npcs"` 结构的初始状态字典** -> 调用 `GameState.initialize_for_new_game()` -> 发出 `new_game_initialized` 信号 -> (后续逻辑) 切换场景 -> 隐藏加载。
|
||||
* **载入存档:** (UI 调用 `SaveLoadManager.load_game(slot_id)` 得到 `save_data` 字典) -> (UI 调用 `load_game_process(save_data)`) -> 显示加载 -> (可选：确保 `InitialDataManager` 就绪) -> 调用 `GameState.restore_state(save_data)` -> 发出 `game_loaded` 信号 -> (后续逻辑) 切换场景 -> 隐藏加载。
|
||||
* 在每个关键步骤后检查成功/失败状态，失败则中止流程并反馈用户。
|
||||
|
||||
@ -74,14 +75,15 @@
|
||||
* 实现数据与游戏逻辑代码的分离。
|
||||
|
||||
### 核心职责 (Responsibilities)
|
||||
* **数据读取与解析:** 从 `res://Data/` 下的 `.json` 文件加载数据 (当前仅加载 `Init_Base.json` 和 `task_development.json`)。
|
||||
* **数据读取与解析:** 从 `res://Data/` 下的 `.json` 文件加载数据 (当前加载 `Init_Base.json`, `task_development.json`, 和 `npc.json`)。
|
||||
* **数据存储与缓存:** 内部存储解析后的数据，确保只加载一次。
|
||||
* **数据提供:** 通过函数接口提供数据的**深拷贝**副本。
|
||||
|
||||
### **对外接口 (Public API / Data Access Functions)**
|
||||
* `ensure_data_loaded() -> bool`: 确保所有必需的初始数据 (`Init_Base.json`, `task_development.json`) 已加载。通常由 `InitializationManager` 在新游戏流程开始时调用。返回加载是否成功。
|
||||
* `ensure_data_loaded() -> bool`: 确保所有必需的初始数据 (`Init_Base.json`, `task_development.json`, `npc.json`) 已加载。通常由 `InitializationManager` 在新游戏流程开始时调用。返回加载是否成功。
|
||||
* `get_starting_settings() -> Dictionary`: 获取 `Init_Base.json` 中的初始游戏设定。返回数据的深拷贝。
|
||||
* `get_task_development_data() -> Dictionary`: 获取 `task_development.json` 中的所有数据。返回数据的深拷贝。
|
||||
* `get_npc_initial_data() -> Dictionary`: 获取 `npc.json` 中的所有数据。返回数据的深拷贝。
|
||||
* **数据规范:** 返回的数据结构遵循 JSON 文件结构。所有通过此管理器获取的数据都应视为**只读**。
|
||||
|
||||
### **对外信号 (Public Signals)**
|
||||
@ -91,7 +93,7 @@
|
||||
* **被调用:** `InitializationManager` (用于构建初始状态字典), 以及任何需要在运行时查询基础静态配置的模块（如 UI 显示、逻辑判断等）。
|
||||
|
||||
### 数据处理 (Data Handled)
|
||||
* **输入:** `res://Data/` 路径下的 `Init_Base.json`, `task_development.json` 文件。
|
||||
* **输入:** `res://Data/` 路径下的 `Init_Base.json`, `task_development.json`, `npc.json` 文件。
|
||||
* **输出:** 解析后的 Godot 数据结构（字典），通过函数接口提供（作为深拷贝副本）。
|
||||
|
||||
### 配置 (Configuration)
|
||||
@ -106,7 +108,7 @@
|
||||
* 提供**通用**的 Key-Value 接口供其他系统**存储和检索**游戏状态数据。
|
||||
* **不理解**存储数据的具体含义或结构。
|
||||
* 在状态数据被完全初始化或恢复后，通知所有监听模块。
|
||||
* 管理游戏暂停状态。
|
||||
* 管理游戏暂停状态**及其他系统级状态（如是否在任务中），这些状态统一存储在 `_state_data` 的 `"system_status"` 键下的字典中。**
|
||||
|
||||
### 核心职责 (Responsibilities)
|
||||
* **状态存储:** 内部维护一个核心字典 (`_state_data`)，用于存储所有动态游戏状态的 Key-Value 对。
|
||||
@ -114,7 +116,7 @@
|
||||
* **状态初始化:** 提供 `initialize_for_new_game` 方法，使用初始设置数据填充状态字典，完成后发出 `state_initialized` 信号。
|
||||
* **状态恢复与通知:** 提供 `restore_state` 方法用于接收并覆盖整个状态字典，完成后发出 `state_restored` 信号。
|
||||
* **存档数据提供:** 提供 `get_savable_state` 方法，返回内部状态字典的**深拷贝**副本，供 `SaveLoadManager` 使用。
|
||||
* **暂停管理:** 提供 `pause_game` 和 `resume_game` 方法来控制内部的 `game_pause` 标志。
|
||||
* **系统状态管理:** 通过内部的 `"system_status"` 字典（存储在 `_state_data["system_status"]`）管理如游戏暂停 (`game_pause`)、是否在任务中 (`is_on_task`) 等状态。提供方法来修改和查询这些特定状态。
|
||||
|
||||
### **对外接口 (Public API / Generic State Access)**
|
||||
|
||||
@ -123,8 +125,11 @@
|
||||
* `get_savable_state() -> Dictionary`: **(供 SaveLoadManager 调用)** 返回内部 `_state_data` 字典的**深拷贝** (`duplicate(true)`)，用于存档，确保返回的是当前状态的一个独立快照。
|
||||
* `get_value(key: String, default = null) -> Variant`: 根据 `key` 从内部字典检索 `value`。如果 `key` 不存在，返回 `default` 值。
|
||||
* `set_value(key: String, value: Variant) -> void`: 向内部字典设置或更新一个 Key-Value 对。**注意：调用者负责确保 `value` 是可序列化的，并进行必要的业务逻辑验证。** 只有当新值与旧值**通过 `!=` (浅比较) 判断为不同**时，才会实际更新并发出 `state_value_changed` 信号。如果 `key` 是 `"time"` 且 `value` 是字典，还会额外发出 `date_changed` 兼容性信号。
|
||||
* `pause_game() -> void`: 将内部 `game_pause` 标志设置为 `true`。
|
||||
* `resume_game() -> void`: 将内部 `game_pause` 标志设置为 `false`。
|
||||
* `pause_game() -> void`: **通过 `set_system_status_value("game_pause", true)` 修改状态，将 `"system_status"` 中的 `game_pause` 设置为 `true`。**
|
||||
* `resume_game() -> void`: **通过 `set_system_status_value("game_pause", false)` 修改状态，将 `"system_status"` 中的 `game_pause` 设置为 `false`。**
|
||||
* `set_system_status_value(key: String, value: bool) -> void`: 设置 `"system_status"` 字典中指定 `key` (`"game_pause"` 或 `"is_on_task"`) 的布尔值。会触发 `state_value_changed` 信号（针对 `"system_status"` 键，传递更新后的整个 `"system_status"` 字典）。
|
||||
* `is_game_paused() -> bool`: 返回游戏是否暂停 (从 `"system_status"` 读取 `game_pause`，若 `"system_status"` 或键不存在则返回 `false`)。
|
||||
* `is_on_task_status() -> bool`: 返回是否处于任务中状态 (从 `"system_status"` 读取 `is_on_task`，若 `"system_status"` 或键不存在则返回 `false`)。
|
||||
|
||||
### **对外信号 (Public Signals)**
|
||||
* `state_initialized(initial_state: Dictionary)`: 在 `initialize_for_new_game` 方法成功执行，内部数据被初始化后发出。传递初始化后的状态字典的副本。
|
||||
@ -133,7 +138,7 @@
|
||||
* `date_changed(new_date: Dictionary)`: **[兼容性信号]** 当 `set_value` 更新了键为 `"time"` 的状态，并且其新值为字典类型时发出。主要用于保持与旧代码或特定UI（如日期显示）的兼容性。传递新日期字典的副本。
|
||||
|
||||
### 数据处理 (Data Handled)
|
||||
* **核心:** 管理一个包含所有动态游戏状态的 Key-Value 字典 (`_state_data`) 和一个布尔型的暂停标志 (`game_pause`)。
|
||||
* **核心:** 管理一个包含所有动态游戏状态的 Key-Value 字典 (`_state_data`)。**系统级状态如暂停 (`game_pause`) 和是否在任务中 (`is_on_task`) 被存储在 `_state_data` 下的 `"system_status"` 子字典中。**
|
||||
* **数据规范:** 不强制规定具体 Key 或 Value 的结构，由各个功能模块自行定义和管理。仅要求 Value 是可序列化的 `Variant`。
|
||||
|
||||
### 配置 (Configuration)
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user