AngelWarmSmile123/twin-angels-en

The Embrace of the Twin Angels (双生天使的怀抱) — English Reference Edition

A data-driven Ren'Py visual novel about existential protection: an angel companion guards a girl's sense of self-worth across a 16-sephirot emotional journey — specified, built, and verified like software, not prose.

This is the English mirror of the Chinese original (爱的游戏). All game content (dialogue, narrative text, angel intervention lines, red-team-style undertow descriptions) is intentionally kept in Chinese verbatim — it is the product itself; every structural comment and all design documentation is fully translated so engineers can follow every system without reading Chinese.

Why this project matters to AI/engineering audiences

The game is essentially an interactive specification of emotionally-safe AI behavior:

Game system	Engineering substance
16 sephiroth progression	State machine with unlock rules, dual completion semantics (FULL/HALF), no-failure design
Five-beat structure (ENCOUNTER→STRUGGLE→COMFORT→CHOICE→TRANSFORM)	Enforced beat ordering with backward-transition validation
Undertows (8 types × 3 intensities)	Data-driven trigger engine (undertow_definitions.json → runtime engine with level resolution, cost formulas, afterimage lifecycle, nihilism guard threshold)
Wing brightness (ADR-004)	Dual-layer numeric model: displayed = max(dynamic_floor, permanent − temporary) with per-phase multipliers
Choice system	Confrontation tags (ENGAGE/ESCAPE/NEUTRAL), escape-count proxy completion at threshold 3
Save system	Slot manager + integrity validation + after-load hooks
Verification-first development	134 pytest cases (unit + integration) run outside the engine against pure-Python mirrors of every system; JSON schema + cross-file consistency validators

The sibling repository heart-protocol-en implements the same existential-protection ideas as production LLM middleware.

Repository layout

design/            GDDs & specs (translated): concept, 5 GDDs, UX spec, art bible
docs/architecture/ Main architecture, variable ownership matrix, ADR-001..004, reviews
production/        Epic breakdown, Batch-0 skeleton, quality gates, sprint plan
game/              The actual Ren'Py project (scripts, systems, JSON data, assets)
tests/             pytest suite (unit + integration) + test framework spec
tools/             validate_data.py / validate_consistency.py / migrations

Quickstart

# Run the full verification suite (no engine needed):
pip install pytest
python -m pytest tests/ -q          # expect: 134 passed

# Data + cross-file consistency validators:
python tools/validate_data.py
python tools/validate_consistency.py

# Play it: open the `game/` folder with Ren'Py SDK 8.3.x

Key design decisions

• Data-driven narrative (ADR-002) — story content lives in JSON; code never hardcodes it.
• Direct calls + interface contracts (ADR-003) — no event bus; every shared variable has exactly one owner (see ownership matrix in docs/architecture/main-architecture.md).
• Dual-layer wing brightness (ADR-004) — permanent damage vs scene-level dimming; Phase 1 multiplier is 0.0 (protection is free while the player learns).
• No FAILED state — three escapes trigger angel-proxy completion at 50% brightness: any player can reach the ending.
• HARM_GUIDE undertow is urgent at all intensities, disables skip, and bypasses delay logic — the one non-negotiable safety rule baked into data, tests, and validators.

Content notice

The game addresses depression, self-worth, and suicidal ideation through protective fiction. Undertow definitions include Chinese-language harm-pattern descriptions used in-fiction to detect and transform them — they are therapeutic design material, not instructions.

License

CC BY-NC-SA 4.0 — see LICENSE.

Acknowledgments

Designed and implemented by 岳祥瑞 (Yue Xiangrui) with AI pair systems, 2026.

Contact

• QQ: 406218898
• WeChat: a13546076748
• Google Email: yuexiangruiyue@gmail.com