| name | godot-genre-romance |
| description | Expert blueprint for romance games and dating sims (Tokimeki Memorial, Monster Prom, Persona social links) focusing on affection systems, multi-stat relationships, dated events, and route branching. Use when building relationship-centric games, social simulations, or otome games. Keywords romance, dating sim, affection system, relationship stats, date events, character routes, love interest. |
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
_process for 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_scale and pause states.
- NEVER leave invisible controls with
MOUSE_FILTER_STOP; strictly set to IGNORE or PASS on 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:
- affection_manager.gd — multi-axial Attraction/Trust/Comfort
- date_event_system.gd — dates + repetition penalty
- route_manager.gd — route lock / CG flags
Original Expert Patterns
Modular Components
Core Loop
- Meet → 2. Schedule / talk → 3. Date / gift → 4. Milestone → 5. Route lock or continue parallel
Decision Trees
Affection & dialogue
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.
## 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).
