| name | xianwen-system-impl |
| description | Implement game systems for Xianwen Online from design docs (docs/redesign/). Covers sect, combat, technique, alchemy, equipment, inventory, world boss, breed/talent systems. Use when implementing new features or fulfilling TODO items from design documents. |
Xianwen Game System Implementation
TODO-driven implementation workflow for game systems, extracted from major development sessions.
Design Document Location
All system designs are in docs/redesign/:
| System | Design Doc | Backend Service | Frontend Store |
|---|
| Condition (體況/心境) | condition-system-redesign.md | condition_service.rs | condition.ts |
| Combat (戰鬥) | combat-system-redesign.md | combat_service.rs | combat.ts |
| Technique (功法/道途) | technique-system-redesign.md | technique_service.rs | technique.ts |
| Sect (宗門) | sect-system-redesign.md | sect_service.rs | sect.ts |
| Equipment (裝備) | equipment-system-redesign.md | equipment_service.rs | equipment.ts |
| Alchemy (煉丹) | alchemy-system-redesign.md | alchemy_service.rs | alchemy.ts |
| Inventory (背包) | inventory-system-redesign.md | inventory_service.rs | inventory.ts |
| World Boss | world-boss-redesign.md | world_boss_service.rs | worldBoss.ts |
| Breed/Talent (品種天賦) | breed-talent-redesign.md | breed_service.rs | breed.ts |
Implementation Workflow
Phase 1: Planning
- Read the design document thoroughly
- Create a TODO file tracking each implementation item
- Identify dependencies between systems
- Break into phases (backend first, then frontend)
Phase 2: Backend Implementation
- Database migration — Create migration in
server/migrations/
- Models — Define in
server/src/models/
- Repository — Data access in
server/src/db/
- Service — Business logic in
server/src/services/
- Handler — API endpoints in
server/src/handlers/
- WebSocket messages — Real-time events in
server/src/ws/
Phase 3: Frontend Implementation
- Types — TypeScript types in
web-client/src/types/
- Store — Pinia store in
web-client/src/stores/
- API integration — WebSocket/REST calls
- Components — Vue components in
web-client/src/components/
- HUD integration — Add buttons/entries to the game HUD
Phase 4: Verification
cargo check && cargo clippy — No backend errorspnpm run build:web — No frontend type errors- Manual testing of the complete flow
- Update the TODO file marking completed items
Critical Design Decisions
These decisions were made across sessions and MUST be followed:
- No AP system — Replaced by
body_condition + mental_condition dual axis
- No player-created sects — Only pre-defined sects (青雲宗, 血煞宗, 天機閣, etc.)
- Dao paths (道途) must be in Chinese — Not English keys
- Intent engine drives gameplay — Player types natural language, server parses intent
- NPC faction boundaries — Righteous NPCs should not wander into demonic territory
- Boss fights should use full combat UI — Not simple click-to-attack
File Size Guidelines
- Services: Keep under 800 lines, split by domain if needed
- Components: Keep under 400 lines, extract sub-components
game.rs was split into domain-specific files (combat.rs, movement.rs, chat.rs)
Common Pitfalls
| Issue | Solution |
|---|
| New columns missing in production | Always create migration, deploy server first |
| Frontend types out of sync | Regenerate types from backend models |
| Quest/task not triggerable | Register in intent engine patterns |
| New feature has no UI entry point | Add HUD button and/or dialog trigger |
| Existing player data incompatible | Write data migration SQL for existing players |
