godot-genre-romance

核心循环

1. 相遇：邂逅潜在恋爱对象，并建立初步好感。
2. 约会：参与有组织的活动，了解对方的偏好并测试彼此是否合拍。
3. 加深关系：投入资源（时间、礼物、选择）来提升好感度／属性。
4. 分支：根据重要里程碑，故事分化为角色专属的“路线”。
5. 结局：根据关系质量，达成专属结局（好／普通／坏）。

绝对不要做的事（专家级反模式）

恋爱与 NPC 逻辑

• 绝不要设计“自动售货机”式的恋爱玩法；必须纳入 NPC 心情、时机 和 多属性阈值 等变量，让角色显得自主。
• 绝不要采用二元好感度（爱／恨）；必须使用 多轴模型（吸引力、信任、舒适度），塑造可信的心理深度。
• 绝不要让属性完全不透明；必须提供 可见指标（爱心 UI、脸红文字、跳动的爱心），帮助玩家做出明智的选择。
• 绝不要落入“约会地点顺序相同”的陷阱；必须对连续两次访问同一地点实施 重复惩罚（约 30%）。
• 绝不要遗漏“可能错过”的里程碑；必须确保后果有实际意义（例如因日程安排不当而错过活动），为体验增添分量。
• 绝不要忽视 NPC 的自主性；必须允许 NPC 拥有自己的 日程安排，并能根据低信任度或活动冲突 拒绝 玩家。
• 绝不要用轮询（_process）检查 NPC 日程；必须使用 信号驱动的 TimeManager（Autoload），广播小时／日期变化，以高效更新状态。
• 绝不要在嫉妒逻辑中硬编码角色引用；必须使用 群组（add_to_group） 在整个场景中广播恋爱事件，让 NPC 能以松耦合的方式自主响应。

技术与 UI

• 绝不要用 _process 实现打字机文本；必须使用作用于 visible_ratio 的 Tweens，实现不受帧率影响的平滑显示。
• 绝不要在主线程解析大型叙事文件；必须使用 ResourceLoader.load_threaded_request()，避免场景切换卡顿。
• 绝不要在好感度检查中使用精确浮点数运算；必须使用 is_equal_approx()，避免因抖动导致逻辑失效。
• 绝不要完全用代码编写复杂对话；必须将对话树设计为 自定义 Resource 类，使叙事数据与逻辑解耦。
• 绝不要依赖全局 OS 时钟处理限时选择；必须使用尊重 Engine.time_scale 和暂停状态的 SceneTreeTimer。
• 绝不要让不可见控件使用 MOUSE_FILTER_STOP；对于非不透明图层上的控件，必须设为 IGNORE 或 PASS，避免阻断对话推进。
• 绝不要硬编码对话文本；必须将文本映射到 本地化键，并通过 tr() 获取，以支持国际化。
• 绝不要使用绝对像素定位界面；必须依赖 锚点和容器，以适应不同设备的缩放。

---

🛠 专家组件（scripts/）

实现对应系统前必须阅读：

1. affection_manager.gd — 多轴吸引力／信任／舒适度
2. date_event_system.gd — 约会与重复惩罚
3. route_manager.gd — 路线锁定／CG 标记

原创专家模式

• affection_manager.gd - 多轴吸引力／信任／舒适度追踪与礼物逻辑。
• date_event_system.gd - 考虑多样性的约会与重复惩罚。
• route_manager.gd - 基于标记的路线分支与 CG 画廊持久化。

模块化组件

• romance_mood_manager.gd - 用于限制对话选项的心情修正项。
• dialogue_expression_parser.gd - 用于切换肖像的表情 / 情绪标签。
• global_affection_tracker.gd - 跨场景的 Autoload 好感度轴快照。
• romance_patterns.gd - 打字机补间动画和爱心迸发效果辅助工具。
• ui_feedback.gd - 在好感度里程碑触发爱心迸发 Tween 效果。
• npc_schedule.gd - NPCSchedule Resource + hour_changed 路由。
• seasonal_dialogue.gd - 季节 / 节日对话键覆盖。
• player_romance_manager.gd - 在约会开始时通过 call_group 广播嫉妒状态。

---

核心循环

1. 相遇 → 2. 安排日程 / 交谈 → 3. 约会 / 送礼 → 4. 里程碑 → 5. 锁定路线或继续并行发展

决策树

好感度与对话

需求	操作
多轴属性	必需 affection_manager.gd
全局 HUD / 嫉妒分组	global_affection_tracker.gd + call_group
由心情限制的台词	romance_mood_manager.gd
肖像标签	dialogue_expression_parser.gd

路线与并行约会

情况	选择
游戏前期探索	保持路线未锁定；自由提升吸引力；信任度限制更深入的个人剧情
游戏中期的专属告白	当信任度 ≥ 阈值且玩家接受时，通过 route_manager.gd锁定路线 — 冻结竞争者恋爱标记
并行约会幻想	允许多条吸引力进度，但发现重叠关系时，嫉妒分组会降低信任度
告白准备情况	吸引力会触发提示；信任度决定成功或委婉拒绝；舒适度可降低限时选项中慌乱失败的概率

不要重新内联好感度 / 约会 / 路线类的存根 — 加载上面的脚本。

技能链

阶段	技能	用途
1. 属性	dictionaries，resources	多轴好感度
2. 时间线	autoload-architecture，signals	日程 / 日期
3. 叙事	godot-dialogue-system，visual-novel	分支选择
4. 持久化	godot-save-load-systems	路线、CG、标记
5. 效果	ui-theming，godot-tweening	爱心 / 脸红

常见陷阱

陷阱	解决方案
自动售货机式恋爱	多轴属性 + 约会重复惩罚
属性不透明	在 UI 中展示吸引力 / 信任度 / 舒适度的变化
脚本索引混乱	使用上面的文件名（不要使用不完整的路径片段）

深入了解超出决策树和脚本目录范围的内容时，必须查看 romance-systems-deep.md。首次接线时不要加载 — 先使用捆绑的 scripts/。

架构概览

1. 好感度管理器（核心）

处理所有角色的复杂关系属性和礼物偏好。

## Godot-Specific Tips

*   **Resources for Characters**: Use `CharacterProfile` resources to store base stats, sprites, and gift preferences.
*   **RichTextLabel Animations**: Use custom BBCode for "blushing" text (pulsing pink) or "nervous" text (shaking).
*   **Dialogic Integration**: While this skill focuses on the *systems*, pairing it with Godot's **Dialogic** plugin is highly recommended for handling the actual dialogue boxes.

## Reference

> Progressive disclosure: open Official Documentation links only when researching a specific API;
> load Related Skills when routing work to a peer domain — do not preload the whole lattice.

### Official Documentation
- [Resources](https://docs.godotengine.org/en/stable/tutorials/scripting/resources.html) — Author `CharacterProfile`, date locations, and seasonal dialogue as data Resources instead of hardcoded trees.
- [Singletons (Autoload)](https://docs.godotengine.org/en/stable/tutorials/scripting/singletons_autoload.html) — Host TimeManager / global affection trackers so schedules and stats survive scene changes.
- [Using signals](https://docs.godotengine.org/en/stable/getting_started/step_by_step/signals.html) — Drive milestones, `stats_changed`, and hour/day clocks without `_process` polling.
- [Groups](https://docs.godotengine.org/en/stable/tutorials/scripting/groups.html) — Broadcast date starts to `romantic_interests` for jealousy without hardcoding NPC refs.
- [BBCode in RichTextLabel](https://docs.godotengine.org/en/stable/tutorials/ui/bbcode_in_richtextlabel.html) — Blush, shake, and custom emotive effects for dating-sim dialogue juice.
- [Evaluating expressions](https://docs.godotengine.org/en/stable/tutorials/scripting/evaluating_expressions.html) — Gate choices with runtime `Expression` checks against affection / route flags.
- [Saving games](https://docs.godotengine.org/en/stable/tutorials/io/saving_games.html) — Persist routes, CG gallery unlocks, and multi-axis relationship dictionaries.
- [Background loading](https://docs.godotengine.org/en/stable/tutorials/io/background_loading.html) — Thread-load large narrative Resources so route transitions do not hitch.
- [Internationalizing games](https://docs.godotengine.org/en/stable/tutorials/i18n/internationalizing_games.html) — Map dialogue and choice text through `tr()` / localization keys.
- [Size and anchors](https://docs.godotengine.org/en/stable/tutorials/ui/size_and_anchors.html) — Keep heart UI and choice panels responsive without absolute pixel layouts.
- [Pausing games](https://docs.godotengine.org/en/stable/tutorials/scripting/pausing_games.html) — Timed choices and romance menus must respect `SceneTree` pause / `time_scale`.
- [Tween](https://docs.godotengine.org/en/stable/classes/class_tween.html) — Typewriter `visible_ratio` and heart-burst pulses without `_process` timers.

### Related Skills

#### Prerequisites
- [godot-resource-data-patterns](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-resource-data-patterns/SKILL.md) — Character profiles, gift tables, and `DateLocation` data belong in typed Resources before wiring affection math.
- [godot-autoload-architecture](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-autoload-architecture/SKILL.md) — Global affection / TimeManager singletons need correct boot order and ownership so route state is not scene-local.
- [godot-signal-architecture](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-signal-architecture/SKILL.md) — Milestone, mood, and schedule buses must stay Signal-Up so UI and NPCs never poll relationship dictionaries.
- [godot-dialogue-system](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-dialogue-system/SKILL.md) — Branching conversation trees and choice consequences are the narrative substrate under affection gates.

#### Complements
- [godot-genre-visual-novel](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-genre-visual-novel/SKILL.md) — Pair route locks and CG gallery with VN presentation (portraits, backgrounds, advance UX).
- [godot-ui-rich-text](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-ui-rich-text/SKILL.md) — Custom BBCode / RichTextEffect patterns for blushing, nervous shake, and meta-linked choices.
- [godot-tweening](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-tweening/SKILL.md) — Typewriter reveals, portrait crossfades, and heart-burst juice without frame-tied timers.
- [godot-save-load-systems](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-save-load-systems/SKILL.md) — Serialize multi-axis stats, route flags, and gallery unlocks with a real save pipeline.
- [godot-inventory-system](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-inventory-system/SKILL.md) — Gift items and diminishing-return histories plug into affection via inventory ownership.
- [godot-ui-theming](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-ui-theming/SKILL.md) — Heart meters, blush chrome, and choice panels stay consistent across romance UI scenes.

#### Downstream / consumers
- [godot-monte-carlo-balancer](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-monte-carlo-balancer/SKILL.md) — Tune gift values, date thresholds, and repetition penalties so routes stay reachable without grind or soft-locks.
- [godot-quest-system](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-quest-system/SKILL.md) — Expose confession deadlines and missable milestones as timed quest gates on the calendar.
- [godot-audio-systems](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-audio-systems/SKILL.md) — Mood overlays and route beats usually need BGM / stinger buses coordinated with affection events.

#### Master
- [godot-master](https://github.com/thedivergentai/gd-agentic-skills/blob/main/skills/godot-master/SKILL.md) — Library router and mirrored module entry for discovering romance peers (dialogue, VN, save, UI).