From 782b1f170196ffd66ad9eca1c8d0f11424914869 Mon Sep 17 00:00:00 2001 From: chen Date: Mon, 3 Aug 2026 22:25:43 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=8C=89=20Godot=20=E8=A7=84=E8=8C=83?= =?UTF-8?q?=E4=BC=98=E5=8C=96=E5=85=A8=E9=83=A8=20GDScript=20=E6=B3=A8?= =?UTF-8?q?=E9=87=8A?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 类/信号/方法添加 ## 文档注释与 @param 标签 - 清理 pass 占位残留 --- src/Core/GameState.gd | 10 ++++- src/Core/MainGame.gd | 6 +-- src/Core/Settings.gd | 9 ++++- src/Core/TimeSystem.gd | 64 ++++++++++++++++++++++++++---- src/UI/HUD/top_bar_hud.gd | 12 ++++++ src/UI/Panels/MainMenu/MainMenu.gd | 17 ++++---- src/UI/Panels/SavePanel.gd | 6 ++- src/UI/Panels/SaveSlot.gd | 14 +++++++ 8 files changed, 115 insertions(+), 23 deletions(-) diff --git a/src/Core/GameState.gd b/src/Core/GameState.gd index ac5eb6f..d35dcb1 100644 --- a/src/Core/GameState.gd +++ b/src/Core/GameState.gd @@ -1,15 +1,21 @@ +## 全局游戏状态（Autoload 单例）。 +## 负责场景间参数传递与会话状态管理，不持有游戏内数据。 extends Node +## 进入游戏的方式。 enum GameMode { NEW_GAME, LOAD_GAME } +## 当前进入游戏的方式。 var mode: GameMode = GameMode.NEW_GAME +## 要加载的存档 ID（仅 LOAD_GAME 时有效）。 var save_id: String = "" -# 游戏内时间（12 月 × 30 天 = 360 天/年） +# 游戏内时间（12 月 × 30 天 = 360 天/年），实际推进由 TimeSystem 负责 var year: int = 1 var month: int = 1 var day: int = 1 +## 请求开始新游戏：重置模式与时间。 func request_new_game() -> void: mode = GameMode.NEW_GAME save_id = "" @@ -17,6 +23,8 @@ func request_new_game() -> void: month = 1 day = 1 +## 请求加载指定存档。 +## @param id: 存档 ID func request_load_game(id: String) -> void: mode = GameMode.LOAD_GAME save_id = id diff --git a/src/Core/MainGame.gd b/src/Core/MainGame.gd index 47f5a81..20b9d90 100644 --- a/src/Core/MainGame.gd +++ b/src/Core/MainGame.gd @@ -1,11 +1,11 @@ +## 主游戏世界场景入口（挂载于 MainGame.tscn）。 +## 进入游戏时根据 GameState 模式初始化，并连接顶部 HUD 信号。 extends Node func _ready() -> void: TimeSystem.speed_index = Settings.default_speed_index TimeSystem.speed = TimeSystem.SPEEDS[TimeSystem.speed_index] - pass - +## 顶部 HUD 的返回主菜单请求。 func _on_top_bar_hud_sign_return_mainmenu() -> void: get_tree().change_scene_to_file("res://src/UI/Panels/MainMenu/MainMenu.tscn") - pass # Replace with function body. diff --git a/src/Core/Settings.gd b/src/Core/Settings.gd index da88788..73f39eb 100644 --- a/src/Core/Settings.gd +++ b/src/Core/Settings.gd @@ -1,13 +1,20 @@ +## 用户设置（Autoload 单例）。 +## 负责个人偏好设置的持久化，保存于 user:// 目录，与游戏存档分离。 extends Node +## 设置文件的保存路径。 const SAVE_PATH := "user://settings.cfg" -var default_speed_index := 1 # 默认 5x +## 新游戏开局时的默认流速档位索引（1 = 5x）。 +var default_speed_index := 1 + +## 从磁盘加载设置（不存在则保持默认值）。 func load_settings() -> void: var cfg := ConfigFile.new() if cfg.load(SAVE_PATH) == OK: default_speed_index = cfg.get_value("time", "speed_index", 1) +## 将当前设置写入磁盘。 func save_settings() -> void: var cfg := ConfigFile.new() cfg.set_value("time", "speed_index", default_speed_index) diff --git a/src/Core/TimeSystem.gd b/src/Core/TimeSystem.gd index b9b61e8..49af8e3 100644 --- a/src/Core/TimeSystem.gd +++ b/src/Core/TimeSystem.gd @@ -1,21 +1,46 @@ +## 全局时间系统（Autoload 单例）。 +## 负责游戏时间的推进与播报，仅在世界场景中运行。 +## 历法：12 月 × 30 日 = 360 日/年。 extends Node -signal day_passed(year, month, day) -signal month_passed(year, month) -signal year_passed(year) -signal speed_changed(speed_index) -signal pause_changed(paused) +## 每当推进一日后发出。 +## @param year: 当前年份 +## @param month: 当前月份（1-12） +## @param day: 当前日（1-30） +signal day_passed(year: int, month: int, day: int) +## 每当进入新月份时发出（同一天内 day_passed 之后）。 +## @param year: 当前年份 +## @param month: 当前月份（1-12） +signal month_passed(year: int, month: int) +## 每当进入新年份时发出（同一天内 month_passed 之后）。 +## @param year: 当前年份 +signal year_passed(year: int) +## 时间流速档位变化时发出。 +## @param speed_index: 新档位在 SPEEDS 中的索引 +signal speed_changed(speed_index: int) +## 暂停状态变化时发出。 +## @param paused: 是否已暂停 +signal pause_changed(paused: bool) +## 可选的时间流速倍率档位。 const SPEEDS := [1.0, 5.0, 20.0] +## 每月的天数。 const DAYS_PER_MONTH := 30 +## 每年的月数。 const MONTHS_PER_YEAR := 12 - -var speed_index := 0 +## 现实世界每 1 天对应的时长（秒）。 const DAY_LENGTH := 0.5 + +## 当前流速档位在 SPEEDS 中的索引。 +var speed_index := 0 +## 当前流速倍率（与 SPEEDS[speed_index] 保持一致）。 var speed := 1.0 +## 是否暂停时间推进。 var paused := false +## 已累积的现实时间（秒），未满 1 天。 var _elapsed := 0.0 + func _process(delta: float) -> void: if paused or not _is_in_game(): return @@ -24,10 +49,14 @@ func _process(delta: float) -> void: _elapsed -= DAY_LENGTH _advance() + +## 判断当前场景是否为游戏世界场景（主菜单/存档界面不推进时间）。 func _is_in_game() -> bool: var scene := get_tree().current_scene return scene != null and scene.name == "MainGame" + +## 推进一日并广播对应信号，跨月/跨年时补发 month_passed / year_passed。 func _advance() -> void: var new_month := false var new_year := false @@ -46,37 +75,58 @@ func _advance() -> void: if new_year: year_passed.emit(GameState.year) + +## 循环切换下一档流速，返回新倍率。 func cycle_speed() -> float: speed_index = (speed_index + 1) % SPEEDS.size() speed = SPEEDS[speed_index] speed_changed.emit(speed_index) return speed + +## 直接设置流速档位（越界自动钳制）。 +## @param index: 目标档位索引 func set_speed_index(index: int) -> void: speed_index = clampi(index, 0, SPEEDS.size() - 1) speed = SPEEDS[speed_index] speed_changed.emit(speed_index) + +## 切换暂停状态，返回切换后的暂停状态。 func toggle_pause() -> bool: paused = not paused pause_changed.emit(paused) return paused + +## 显式设置暂停状态（幂等，状态未变化时不发信号）。 +## @param value: 目标暂停状态 func set_paused(value: bool) -> void: if paused == value: return paused = value pause_changed.emit(paused) + +## 当前流速的显示文本，如 "x5"。 func get_speed_label() -> String: return "x%d" % int(speed) + +## 当前日期数组 [年, 月, 日]。 func get_current_date() -> Array: return [GameState.year, GameState.month, GameState.day] + +## 当前日期文本，如 "3年 5月 12日"。 func get_date_text() -> String: return "%d年 %d月 %d日" % [GameState.year, GameState.month, GameState.day] + +## 直接设置日期（供读档/测试使用）。 +## @param y: 年 +## @param m: 月（1-12） +## @param d: 日（1-30） func set_date(y: int, m: int, d: int) -> void: GameState.year = y GameState.month = m diff --git a/src/UI/HUD/top_bar_hud.gd b/src/UI/HUD/top_bar_hud.gd index 257e31a..74f0991 100644 --- a/src/UI/HUD/top_bar_hud.gd +++ b/src/UI/HUD/top_bar_hud.gd @@ -1,9 +1,15 @@ +## 顶部信息栏 HUD（挂载于 TopBarHUD.tscn）。 +## 显示灵石/时间/声望，提供时间流速控制与返回主菜单入口。 extends Control +## 请求返回主菜单。 signal sign_return_mainmenu +## 三个流速按钮的节点名（与 tscn 中的 SpeedGroup 子节点对应）。 const SPEED_BUTTONS := ["Button_Speed1", "Button_Speed5", "Button_Speed20"] +## 激活档位按钮颜色。 const ACTIVE_COLOR := Color(1.0, 1.0, 1.0) +## 未激活档位按钮颜色。 const INACTIVE_COLOR := Color(0.55, 0.55, 0.55) func _ready() -> void: @@ -14,20 +20,26 @@ func _ready() -> void: _update_speed_ui() $HBoxContainer/Value_Time.text = TimeSystem.get_date_text() +## 每日推进时刷新日期显示。 func _on_day_passed(_year: int, _month: int, _day: int) -> void: $HBoxContainer/Value_Time.text = TimeSystem.get_date_text() +## 点击"返回"按钮。 func _on_button_return_button_up() -> void: sign_return_mainmenu.emit() +## 点击暂停/继续按钮，切换后刷新按钮状态。 func _on_button_pause_button_up() -> void: TimeSystem.toggle_pause() _update_speed_ui() +## 点击流速档位按钮。 +## @param index: 目标档位索引（由 _ready 中 bind 传入） func _on_speed_button_up(index: int) -> void: TimeSystem.set_speed_index(index) _update_speed_ui() +## 刷新速度组 UI：暂停按钮文字与各档位高亮状态。 func _update_speed_ui() -> void: var pause_btn: Button = $HBoxContainer/SpeedGroup/Button_Pause pause_btn.text = "继续" if TimeSystem.paused else "暂停" diff --git a/src/UI/Panels/MainMenu/MainMenu.gd b/src/UI/Panels/MainMenu/MainMenu.gd index 5f37c94..ba77ab9 100644 --- a/src/UI/Panels/MainMenu/MainMenu.gd +++ b/src/UI/Panels/MainMenu/MainMenu.gd @@ -1,26 +1,25 @@ +## 主菜单场景（挂载于 MainMenu.tscn）。 extends Control +## 点击"新游戏"：重置 GameState 后进入游戏世界。 func MainMenu_NewGame_ButtonUp() -> void: GameState.request_new_game() get_tree().change_scene_to_file("res://src/Core/MainGame.tscn") - +## 点击"读取存档"：隐藏主按钮组并显示存档面板。 func MainMenu_LoadGame_ButtonUp() -> void: $ButtonGroup.hide() $SavePanel.show() - pass # Replace with function body. - +## 点击"设置"（TODO：接入设置面板）。 func MainMenu_Settings_ButtonUp() -> void: - pass # Replace with function body. - + pass +## 点击"退出"。 func MainMenu_Quit_ButtonUp() -> void: - get_tree().quit(); - pass # Replace with function body. - + get_tree().quit() +## 存档面板请求返回。 func _on_save_panel_back_pressed() -> void: $SavePanel.hide() $ButtonGroup.show() - pass # Replace with function body. diff --git a/src/UI/Panels/SavePanel.gd b/src/UI/Panels/SavePanel.gd index 69113db..6f6d7ab 100644 --- a/src/UI/Panels/SavePanel.gd +++ b/src/UI/Panels/SavePanel.gd @@ -1,8 +1,10 @@ +## 存档选择面板（挂载于 SavePanel.tscn）。 +## 显示存档列表与"新建存档"入口，通过信号通知外部结果。 extends PanelContainer +## 请求关闭面板（返回上级界面）。 signal back_pressed - +## 点击"返回"按钮。 func _on_button_esc_button_up() -> void: back_pressed.emit() - pass # Replace with function body. diff --git a/src/UI/Panels/SaveSlot.gd b/src/UI/Panels/SaveSlot.gd index 4b1dcd2..e66c1bf 100644 --- a/src/UI/Panels/SaveSlot.gd +++ b/src/UI/Panels/SaveSlot.gd @@ -1,5 +1,9 @@ +## 存档槽位条目（挂载于 SaveSlot.tscn）。 +## 展示单个存档信息；空槽位用于新建存档。 extends PanelContainer +## 槽位被点击时发出，save_id 为空表示点击了新建槽位。 +## @param save_id: 存档 ID signal slot_pressed(save_id: String) @onready var slot_index_label: Label = %SlotIndexLabel @@ -9,9 +13,16 @@ signal slot_pressed(save_id: String) @onready var delete_button: Button = %DeleteButton @onready var arrow_button: Button = %ArrowIcon +## 本槽位对应的存档 ID。 var save_id: String = "" +## 是否已有存档数据（false 表示新建槽位）。 var has_data: bool = false +## 填充为已有存档槽位。 +## @param id: 存档 ID +## @param name_text: 存档名称 +## @param meta1: 第一行元数据 +## @param meta2: 第二行元数据 func setup(id: String, name_text: String, meta1: String, meta2: String) -> void: save_id = id has_data = true @@ -22,6 +33,7 @@ func setup(id: String, name_text: String, meta1: String, meta2: String) -> void: delete_button.visible = true arrow_button.visible = true +## 填充为"新建存档"空槽位。 func setup_empty() -> void: has_data = false slot_index_label.text = "+" @@ -31,8 +43,10 @@ func setup_empty() -> void: delete_button.visible = false arrow_button.visible = false +## 槽位本体被点击。 func _on_pressed() -> void: slot_pressed.emit(save_id) +## 点击删除按钮（TODO：接入确认弹窗）。 func _on_delete_button_button_up() -> void: print("删除存档: ", save_id)