使用方法
- 复制安装命令，在自己的智能体环境安装前先检查源码包。
- 从原始文档核对所需工具、凭据和支持的宿主。
- 说明输入材料与期望交付物，并对照来源检查输出。
npx skills add https://github.com/thedivergentai/game-design-agentic-skills --skill godot-genre-romance开始前需了解
- 安装不包含模型订阅、API 额度或访问文件的权限。
- 仓库星数和安装量反映活跃情况，不等于独立质量或安全测试。
仓库原始内容
按源仓库内容呈现，保留标题、案例、代码、表格、链接以及原文引用的演示图片。
Core Loop
- Meet: Encounter potential love interests and establish baseline rapport.
- Date: Engage in structured events to learn preferences and test compatibility.
- Deepen: Invest resources (time, gifts, choices) to increase affection/stats.
- Branch: Story diverges into character-specific "Routes" based on major milestones.
- Resolve: Reach a specialized ending (Good/Normal/Bad) based on relationship quality.
NEVER Do (Expert Anti-Patterns)
Romance & NPC Logic
- NEVER create "Vending Machine" romance; strictly incorporate variables like NPC Mood, Timing, and Multi-Stat Thresholds to ensure characters feel autonomous.
- NEVER use binary Affection (Love/Hate); strictly use a Multi-Axial Model (Attraction, Trust, Comfort) for believable psychological depth.
- NEVER focus on 100% opaque stats; strictly provide Visible Indicators (heart UI, blushing text, pulsing hearts) to help players make informed choices.
- NEVER use the "Same Date Order" trap; strictly implement a Repetition Penalty (~30%) for visiting the same location twice in a row.
- NEVER forget "Missable" Milestones; strictly ensure meaningful consequences (e.g., missing events due to poor scheduling) to add weight to the experience.
- NEVER ignore NPC Autonomy; strictly allow NPCs to have their own Schedules and the ability to Reject the player based on low trust or conflicting events.
- NEVER use polling (
_process) for NPC schedule checks; strictly use a Signal-Driven TimeManager (Autoload) to broadcast hour/day changes for performant state updates. - NEVER hardcode character references for jealousy logic; strictly use Groups (`add_to_group`) to broadcast romantic events across the scene for decoupled, autonomous NPC reactions.
Technical & UI
- NEVER use
_processfor typewriter text; strictly use Tweens on `visible_ratio` for frame-independent, smooth reveals. - NEVER parse massive narrative files on the main thread; strictly use `ResourceLoader.load_threaded_request()` to prevent transition stutters.
- NEVER use exact float math for affection checks; strictly use `is_equal_approx()` to avoid jitter-based logic failures.
- NEVER structure complex dialogue purely in code; strictly design dialogue trees as Custom `Resource` classes to decouple narrative data from logic.
- NEVER rely on the global OS clock for timed choices; strictly use `SceneTreeTimer` which respects
Engine.time_scaleand pause states. - NEVER leave invisible controls with
MOUSE_FILTER_STOP; strictly set toIGNOREorPASSon non-opaque layers to avoid blocking dialogue progression. - NEVER hardcode dialogue strings; strictly map text to Localization Keys and retrieve via
tr()for internationalization. - NEVER use absolute pixel positioning for interfaces; strictly rely on Anchoring & Containers for responsive scaling across devices.
🛠 Expert Components (scripts/)
MANDATORY reads before implementing the matching system: 1. affection_manager.gd — multi-axial Attraction/Trust/Comfort 2. date_event_system.gd — dates + repetition penalty 3. route_manager.gd — route lock / CG flags
Original Expert Patterns
- affection_manager.gd - Multi-axis Attraction/Trust/Comfort tracking and gift logic.
- date_event_system.gd - Variety-aware dating with repetition penalties.
- route_manager.gd - Flag-based route branching and CG gallery persistence.
Modular Components
- romance_mood_manager.gd - Mood modifiers that gate dialogue options.
- dialogue_expression_parser.gd - Expression / emotion tags for portrait swaps.
- global_affection_tracker.gd - Cross-scene Autoload snapshot of all axes.
- romance_patterns.gd - Typewriter tweens and heart-burst juice helpers.
- ui_feedback.gd - Heart-burst Tween juice at affection milestones.
- npc_schedule.gd -
NPCScheduleResource + hour_changed routing. - seasonal_dialogue.gd - Season/festival dialogue key overrides.
- player_romance_manager.gd -
call_groupjealousy broadcast on date start.
Core Loop
- Meet → 2. Schedule / talk → 3. Date / gift → 4. Milestone → 5. Route lock or continue parallel
Decision Trees
Affection & dialogue
| Need | Action |
|---|---|
| Multi-axis stats | MANDATORY affection_manager.gd |
| Global HUD / jealousy groups | global_affection_tracker.gd + call_group |
| Mood-gated lines | romance_mood_manager.gd |
| Portrait tags | dialogue_expression_parser.gd |
Routes vs parallel dating
| Situation | Choice |
|---|---|
| Early game exploration | Keep routes unlocked; raise Attraction freely; Trust gates deeper personal scenes |
| Mid-game exclusive confession | Lock route via route_manager.gd when Trust ≥ threshold and player accepts — freeze rival romance flags |
| Parallel dating fantasy | Allow multiple Attraction tracks, but jealousy groups cut Trust on discovered overlaps |
| Confession readiness | Attraction opens the prompt; Trust decides success vs soft rejection; Comfort reduces timed-choice panic fail |
Do not re-inline affection/date/route class stubs — load the scripts above.
Skill Chain
| Phase | Skills | Purpose |
|---|---|---|
| 1. Stats | dictionaries, resources | Multi-axis affection |
| 2. Timeline | autoload-architecture, signals | Schedules / days |
| 3. Narrative | godot-dialogue-system, visual-novel | Branching choices |
| 4. Persist | godot-save-load-systems | Routes, CGs, flags |
| 5. Juice | ui-theming, godot-tweening | Hearts / blush |
Common Pitfalls
| Pitfall | Solution |
|---|---|
| Vending-machine romance | Multi-axis + repetition penalty on dates |
| Opaque stats | Surface Attraction/Trust/Comfort deltas in UI |
| Garbled script index | Use filenames above (no broken path fragments) |
MANDATORY for depth beyond decision trees and script catalog: romance-systems-deep.md. Do NOT Load on first-pass wiring — use bundled scripts/ first.Architecture Overview
1. Affection Manager (The Heart)
Handles complex relationship stats and gift preferences for all characters.
gdscript
## 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).
