docs: 全局脚本补充文档注释（14 个文件 29 处）

README.md

@@ -149,6 +149,12 @@
 3. "新游戏"直接进入；"读取存档"在存档面板中选择
 4. 游戏内顶部 HUD 可暂停/调速（1x/5x/20x），返回按钮回主菜单
 
+## 导出
+
+1. 编辑器安装 **4.7.1 导出模板**（编辑器 → 管理导出模板）
+2. 项目 → 导出 → Windows Desktop（`export_presets.cfg` 已配置 `all_resources`，输出 `aaa.exe` 单文件含嵌入 PCK）
+3. **约定**：`resources/game_config.cfg` 为未知扩展名，**不随导出打包**——导出版使用 `GameConfig.gd` 代码默认值。修改 cfg 参数后，需同步 `GameConfig.gd` 默认值再导出（注释已标注同步项）。
+
 ## 命名规范
 
 | 类别     | 格式       | 示例                |

export_presets.cfg

@@ -8,7 +8,7 @@ name="Windows Desktop"
 platform="Windows Desktop"
 dedicated_server=false
 custom_features=""
-export_filter="scenes"
+export_filter="all_resources"
 export_files=PackedStringArray()
 include_filter=""
 exclude_filter=""

project.godot

@@ -11,7 +11,7 @@ config_version=5
 [application]
 
 config/name="模拟宗门"
-run/main_scene="uid://d1odycoaqhhyg"
+run/main_scene="res://src/UI/Panels/MainMenu/MainMenu.tscn"
 config/features=PackedStringArray("4.7", "Forward Plus")
 
 [autoload]

src/Character/CultivationManager.gd

@@ -8,6 +8,7 @@ signal realm_changed(d: Disciple)
 signal cultivation_log(text: String)
 
 
+## 挂接每日推进信号。
 func _ready() -> void:
 	# 每日推进时结算全体已入宗弟子的修为与境界
 	TimeSystem.day_passed.connect(_on_day_passed)

src/Character/Disciple.gd

@@ -20,7 +20,7 @@ const REALM_NAMES: Array[String] = ["练气", "筑基", "金丹", "元婴", "化
 var id: int = 0                # 唯一编号（DiscipleManager 分配）
 var name: String = ""
 var age: int = 0
-var aptitude: Aptitude = Aptitude.ORDINARY
+var aptitude: Aptitude = Aptitude.ORDINARY   # 资质（入宗分流结果）
 var roots: Array[SpiritRoot] = []   # 普通弟子 1~5 根；天灵根固定 1 根
 var is_heavenly: bool = false       # 天灵根标记（仅天骄资质，概率见配置）
 var join_year: int = 0              # 入宗年份（0 = 未入宗/候选），accept 时快照
@@ -35,6 +35,7 @@ var hunger_days: int = 0            # 断粮累计天数（≥阈值离宗，方
 func get_aptitude_name() -> String:
 	return APTITUDE_NAMES[aptitude]
 
+## 灵根显示文本，如 "金、木"。
 func get_roots_text() -> String:
 	var names: Array[String] = []
 	for root in roots:
@@ -49,6 +50,7 @@ func get_root_count_capacity() -> float:
 		return 0.0
 	return 1.0 / roots.size()
 
+## 境界显示文本，如 "练气5层"、"筑基初期"。
 func get_realm_text() -> String:
 	if realm_index == 0:
 		return "%s%d层" % [REALM_NAMES[realm_index], sub_realm_index + 1]

src/Character/DiscipleManager.gd

@@ -35,6 +35,7 @@ var _days_until_recruit := 0
 var _next_id := 1
 
 
+## 挂接每日推进信号并初始化招募倒计时。
 func _ready() -> void:
 	# 挂到时间系统上：每日推进时倒计时，满间隔生成候选并暂停时间
 	TimeSystem.day_passed.connect(_on_day_passed)

src/Core/GameConfig.gd

@@ -14,7 +14,8 @@ var opening_applicant_count := 5
 ## 开局必须选满数。
 var opening_pick_count := 3
 ## 定期招募间隔（游戏年，1 年 = 360 天）。
-var recruit_interval_years := 0.1
+## 注意：cfg 文件不随导出打包（未知扩展名），导出版使用此默认值——与 cfg 保持同步。
+var recruit_interval_years := 12.0
 ## 定期弹窗候选人数。
 var recruit_applicant_count := 3
 ## 天灵根概率（仅天骄资质中再掷一次）。
@@ -39,8 +40,8 @@ var level_thresholds: Array[float] = [100.0, 200.0, 350.0, 550.0, 800.0, 1100.0,
 var bottleneck_levels: Array[int] = [4, 7, 10, 13]
 
 # —— UI 通用（对应 cfg 的 [ui] 节）——
-## HUD 字体大小。
+## HUD 字体大小（导出版用默认值，与 cfg 保持同步）。
-var hud_font_size := 32
+var hud_font_size := 24
 
 # —— 建筑系统（对应 cfg 的 [building] 节）——
 ## 开局赠送灵石（新游戏发放）。
@@ -71,6 +72,7 @@ var aptitude_weights_by_difficulty: Dictionary = {
 }
 
 
+## 启动时加载配置文件。
 func _ready() -> void:
 	_load_config()
 

src/Core/GameState.gd

@@ -13,9 +13,9 @@ var profile_id: int = 0
 var save_slot: String = ""
 
 # 游戏内时间（12 月 × 30 天 = 360 天/年），实际推进由 TimeSystem 负责
-var year: int = 1
+var year: int = 1   # 年
-var month: int = 1
+var month: int = 1  # 月（1-12）
-var day: int = 1
+var day: int = 1    # 日（1-30）
 
 ## 请求开始新游戏。
 ## @param pid: 新存档组 ID（主菜单创建）

src/Core/MainGame.gd

@@ -2,6 +2,7 @@
 ## 进入游戏时根据 GameState 模式初始化，并连接顶部 HUD 信号。
 extends Node
 
+## 进入游戏世界：注册场景分组，按 GameState 模式初始化（新游戏/读档）。
 func _ready() -> void:
 	# 注册为游戏世界场景（供 TimeSystem 判断是否推进时间）
 	add_to_group("game_scene")

src/Core/SectManager.gd

@@ -10,40 +10,58 @@ var reputation := 0         # 声望
 var food := 0               # 灵米（食物资源，HUD 显示"灵米"）
 
 
+## 增加灵石并广播信号。
+## @param amount: 增加量
 func add_spirit_stones(amount: int) -> void:
 	spirit_stones += amount
 	emit_signal("spirit_stones_changed", spirit_stones, amount)
 
+## 减少灵石并广播信号。
+## @param amount: 减少量
 func remove_spirit_stones(amount: int) -> void:
 	spirit_stones -= amount
 	emit_signal("spirit_stones_changed", spirit_stones, -amount)
 
+## 增加声望并广播信号。
+## @param amount: 增加量
 func add_reputation(amount: int) -> void:
 	reputation += amount
 	emit_signal("reputation_changed", reputation, amount)
 
+## 减少声望并广播信号。
+## @param amount: 减少量
 func remove_reputation(amount: int) -> void:
 	reputation -= amount
 	emit_signal("reputation_changed", reputation, -amount)
 
+## 增加灵米并广播信号。
+## @param amount: 增加量
 func add_food(amount: int) -> void:
 	food += amount
 	emit_signal("food_changed", food, amount)
 
+## 减少灵米并广播信号。
+## @param amount: 减少量
 func remove_food(amount: int) -> void:
 	food -= amount
 	emit_signal("food_changed", food, -amount)
 
+## 直接设定灵石（读档/新游戏用，带信号 HUD 自动刷新）。
+## @param value: 目标值
 func set_spirit_stones(value: int) -> void:
 	var delta := value - spirit_stones
 	spirit_stones = value
 	spirit_stones_changed.emit(spirit_stones, delta)
 
+## 直接设定声望（读档/新游戏用，带信号 HUD 自动刷新）。
+## @param value: 目标值
 func set_reputation(value: int) -> void:
 	var delta := value - reputation
 	reputation = value
 	reputation_changed.emit(reputation, delta)
 
+## 直接设定灵米（读档/新游戏用，带信号 HUD 自动刷新）。
+## @param value: 目标值
 func set_food(value: int) -> void:
 	var delta := value - food
 	food = value

src/Core/TimeSystem.gd

@@ -41,6 +41,7 @@ var paused := false
 var _elapsed := 0.0
 
 
+## 每帧累积时间，满一天推进日期（仅游戏世界场景内）。
 func _process(delta: float) -> void:
 	if paused or not _is_in_game():
 		return

src/Sect/BuildingManager.gd

@@ -10,6 +10,7 @@ signal buildings_changed
 var buildings: Array[Building] = []
 
 
+## 挂接每日推进信号，结算建筑产出。
 func _ready() -> void:
 	# 每日推进时结算各建筑产出
 	TimeSystem.day_passed.connect(_on_day_passed)

src/UI/HUD/top_bar_hud.gd

@@ -19,6 +19,7 @@ signal sign_open_save
 @onready var pause_button: Button = %Button_Pause
 @onready var speed_buttons: Array[Button] = [%Button_Speed1, %Button_Speed5, %Button_Speed20]
 
+## 初始化：连接速度按钮与各信号、设置初始显示、应用配置字号。
 func _ready() -> void:
 	for i in speed_buttons.size():
 		var btn := speed_buttons[i]

src/UI/Panels/BuildingsPanel/buildings_panel.gd

@@ -10,6 +10,7 @@ extends Control
 var _was_paused := false
 
 
+## 订阅建筑变化信号，默认隐藏。
 func _ready() -> void:
 	BuildingManager.buildings_changed.connect(_on_buildings_changed)
 	visible = false

src/UI/Panels/DisciplesPanel/disciple_detail_panel.gd

@@ -7,6 +7,7 @@ extends Control
 @onready var info_label: Label = %InfoLabel
 
 
+## 默认隐藏。
 func _ready() -> void:
 	visible = false
 

src/UI/Panels/DisciplesPanel/disciples_panel.gd

@@ -18,6 +18,7 @@ const APTITUDE_COLORS := {
 var _was_paused := false
 
 
+## 订阅名录变化信号，默认隐藏。
 func _ready() -> void:
 	# 名录变化时刷新（面板打开期间也同步）
 	DiscipleManager.disciples_changed.connect(_on_disciples_changed)

src/UI/Panels/RecruitPanel/recruit_panel.gd

@@ -18,6 +18,7 @@ var _check_buttons: Array[CheckButton] = []
 var _entry_disciples: Array[Disciple] = []
 
 
+## 订阅候选生成信号，默认隐藏。
 func _ready() -> void:
 	# 订阅候选生成信号：开局与定期招募都会触发
 	DiscipleManager.applicants_generated.connect(_on_applicants_generated)

src/UI/Panels/SaveSlot.tscn

@@ -54,5 +54,5 @@ layout_mode = 2
 size_flags_horizontal = 3
 text = "▶"
 
-[connection signal="button_up" from="HBoxContainer/ArrowIcon" to="." method="_on_arrow_button_up"]
 [connection signal="button_up" from="HBoxContainer/DeleteButton" to="." method="_on_delete_button_button_up"]
+[connection signal="button_up" from="HBoxContainer/ArrowIcon" to="." method="_on_arrow_button_up"]