Castle Siege - Epic

[sven-n]

Overview

Implement the Castle Siege weekly guild-vs-guild event and the tightly-coupled Guild Alliance system in OpenMU. Castle Siege is a large-scale PvP event where alliances of guilds battle for control of a castle, with the winning alliance gaining ownership, tax revenue, and access to exclusive content.

Reference Documentation

• C++ Server Analysis: CastleSiege_GuildAlliance_Documentation.md — detailed reverse-engineering of a random C++ server implementation (Dimension Gamers).
• Implementation Plan: CastleSiege_Implementation_Plan.md — full architectural mapping to OpenMU's plug-in system, data model, persistence, network packets, and game logic layers.
• Per-Phase Details: — individual sub-issues with requirements, file lists, and acceptance criteria.

Architecture Decision

Castle Siege runs on a permanent map (Valley of Loren, map 30) — not a per-instance mini-game map. The chosen pattern is:

• A custom IPeriodicTaskPlugIn (CastleSiegePlugIn) driving the 10-state weekly cycle (OpenMU's PeriodicTaskBasePlugIn only supports 3 states).
• A CastleSiegeContext class holding all runtime state (analogous to GuildWarContext / MiniGameContext).
• One context per IGameServerContext, single-server initially, with interfaces designed for future multi-server support via IEventPublisher.

Phase Breakdown

#	Phase	Dependencies	Issue
1	Guild Alliance System — Alliance CRUD, hostility, IGuildServer extensions, message handlers	None	#720
2	Data Model & Configuration — Enums, config classes, entity types (CastleSiegeConfiguration, CastleSiegeData, etc.)	Phase 1	#721
3	State Machine — 10-state weekly cycle, CastleSiegeContext, CastleSiegePlugIn	Phase 2	#722
4	Registration & Marks — Guild registration, Emblem of Lord mark submission	Phase 3	#723
5	Guild Selection & Participants — Scoring algorithm, join side assignment, participant tracking	Phase 4	#724
6	NPCs — Gates, Statues, Crown, Switches, Levers, Machines + intelligence plug-ins, upgrade/buy/repair	Phase 3	#725
7	Crown & Switch Win-Condition — 3-player capture mechanic, side swap, ownership transfer	Phase 5, 6	#726
8	Siege Warfare Machines — AoE fire at target zones, damage application	Phase 5, 6	#727
9	Life Stones — Guild-summoned healing NPCs with creation phase	Phase 5, 6	#728
10	Tax, Tribute & Economy — Chaos/Store/Hunt taxes, exemptions, tribute withdrawal, hunt zone toggle	Phase 1, 2, 3	#729
11	Mini-Map & Guild Commands — Alliance master position display, directional orders	Phase 5, 6	#730
12	Network Packets — XML packet definitions for all C→S and S→C packets	Incremental	#731
13	Persistence & Data Initialization — EF Core mappings, migrations, Season 6 seed data	Phase 2	#732
14	Admin Panel Integration — Blazor management page, force state transitions, ownership editing	Phase 3	#733
15	Testing — Unit tests for alliance, state machine, selection, crown, tax, NPCs, rewards	Continuous	#734

Dependency Graph

#720 Phase 1 (Alliance)
  └─ #721 Phase 2 (Data Model) ──── #732 Phase 13 (Persistence)
       └─ #722 Phase 3 (State Machine) ──── #731 Phase 12 (Packets, incremental)
            ├─ #723 Phase 4 (Registration)
            │    └─ #724 Phase 5 (Guild Selection)
            │         ├─ #726 Phase 7 (Crown/Switch) ← #725 Phase 6
            │         ├─ #727 Phase 8 (Machines) ← #725 Phase 6
            │         ├─ #728 Phase 9 (Life Stones) ← #725 Phase 6
            │         └─ #730 Phase 11 (Mini-Map) ← #725 Phase 6
            ├─ #725 Phase 6 (NPCs)
            ├─ #729 Phase 10 (Tax/Economy)
            └─ #733 Phase 14 (Admin Panel)
#734 Phase 15 (Testing) ← continuous

Suggested Implementation Order

1. Guild Alliance System #720 – Guild Alliance (enables the whole feature)
2. Castle Siege Data Model & Configuration #721 + Castle Siege Persistence & Data Initialization #732 – Data Model + Persistence (foundational)
3. Castle Siege Network Packets #731 – Network Packets (define incrementally as needed)
4. Castle Siege State Machine #722 – State Machine (the event skeleton)
5. Castle Siege Registration & Mark System #723 – Registration
6. Castle Siege Guild Selection & Participant Tracking #724 – Guild Selection
7. Castle Siege NPCs (Gates, Statues, Crown, Switches, Levers) #725 – NPCs
8. Castle Siege Crown & Switch Win-Condition Mechanics #726 – Crown/Switch Mechanics (core gameplay)
9. Castle Siege Tax, Tribute & Economy #729 – Tax/Economy (can be done in parallel)
10. Castle Siege Warfare Machines #727 – Machines
11. Castle Siege Life Stones #728 – Life Stones
12. Castle Siege Mini-Map & Guild Commands #730 – Mini-Map
13. Castle Siege Admin Panel Integration #733 – Admin Panel
14. Castle Siege Testing Strategy #734 – Testing (dedicated pass at the end)

Estimated Scope

~83 new files, ~22 modified files across DataModel, Interfaces, GuildServer, GameLogic, GameServer, Network.Packets, Persistence, and Web.AdminPanel projects.

Key Design Decisions

1. Custom IPeriodicTaskPlugIn instead of extending PeriodicTaskBasePlugIn — the 10-state cycle doesn't map to the base's 3-state model.
2. Runtime uint guild IDs for network/logic, persistent Guid for database — map at load/save boundaries.
3. Gate terrain blocking via runtime modification of GameMapTerrain attribute bytes.
4. Area-skill-hits-player scoped to the CS map during Start state only.
5. AssistantMaster added to GuildPosition enum for castle NPC management permissions.
6. Single-server first, interfaces designed for future IEventPublisher-based multi-server support.