atfatmc/AdamuSw
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
5549c2bec757df26238de83d3c4a5f6320db12bf
AdamuSw/docs/superpowers/specs/2026-07-14-castle-siege-design.md
Acentech Dev 5549c2bec7
Some checks failed
.NET Core / build (push) Has been cancelled
Details
feat(CS-P3): siege PvP on Valley of Loren during siege (ADAMU-CUSTOM) + golden phase announcements
2026-07-15 01:23:57 +03:00

13 KiB
Raw Blame History

Castle Siege — Çatı Tasarım Spec'i (Architecture)

  • Tarih: 2026-07-14
  • Durum: Onaylandı (kullanıcı) → uygulama planına geçiliyor
  • Kapsam: Bu bir çatı (umbrella) spec'idir. Tam CS tek plana sığmaz; iş fazlara (Faz 0 + P1–P5) bölünmüştür ve her faz kendi detaylı plan → uygulama döngüsünü alır. İlk plan Faz 0 (bootstrap + fork kurulumu) için yazılacaktır.

1. Amaç ve hedef

MuMain S6 mobil client'ına bağlı OpenMU sunucusuna tam fonksiyonel Castle Siege eklemek; bunu, upstream OpenMU güncellemelerini almaya devam edebileceğimiz ve kendi custom işlerimizi (remote-NPC + CS) bozmayan bir fork/derleme/deploy akışıyla yapmak.

Kritik bulgu: client Castle Siege'i zaten biliyor. MuMain S6 kaynağında GMBattleCastle (CS haritası), guild mark işleme, WSclient.cpp içinde CS paket handler'ları hazır. Bu yüzden CS bizim için ~%80 server-side (OpenMU C#) iştir. Client'ta zaten var olan davranışı doğru protokol paketleriyle tetiklemek kalıyor.

2. Gereksinimler

CS ürün gereksinimleri

  1. Tam fonksiyonel CS — tüm resmi mekanikler (kayıt, guild mark/Sign of Lord, kuşatma, taht contention, sahiplik, vergi, Guardian Statue).
  2. Kale sahibine özel av haritası — kale içi hunting zone; yalnızca sahip guild üyeleri (ve alliance) girebilir; özel monster/drop.
  3. Ayarlanabilir döngüler — kayıt/kuşatma süre ve zamanları config'ten (günlük/haftalık/dakikalık test dahil).
  4. Her şey admin kontrolünde — AdminPanel + chat komutları: başlat/durdur, sahip guild'i zorla ata, config düzenle, durum gör, sıfırla.

Deployment / entegrasyon gereksinimleri

  1. Kendi server image'i — stock munique/openmu image + DLL enjeksiyonu bırakılacak; image kaynaktan (src/Startup/Dockerfile) derlenecek, custom kod (remote-NPC + CS) içinde olacak.
  2. Upstream takibi otomatik — AdamuSw'e upstream remote'u; git fetch upstream && git merge upstream/master ile yeni feature'lar alınır. Bu merge'ler NPC + CS işini bozmamalı.
  3. DockerHub deploy — image build → tag → DockerHub push → başka sunucuda ayağa kaldır.

3. Kapsam kararları (netleştirilmiş)

Konu Karar
Fidelity Tam resmi CS
Zamanlama Konfigüre edilebilir döngü (Timetable tabanlı)
Admin Tam admin kontrolü (AdminPanel + chat komutları)
Client değişikliği İlke: minimum. Server'ı client'ın beklediği mevcut S6 CS protokolüne uydur.
Mimari Yaklaşım B: ayrı CastleSiege alt-sistemi; guild + PeriodicTask + MiniGame parçalarını yeniden kullan

4. Repo topolojisi ve rolleri

Konum Rol
d:/OpenMU/ (branch main) Eski customized fork — remote-NPC değişikliklerinin kaynağı (src/GameLogic/PlayerActions/TalkNpcAction.cs, GameMap.cs, TalkNpcHandlerPlugInBase.cs). Dağınık (build artifact'ları commit'lenmiş). Sadece diff kaynağı olarak kullanılacak.
.../OpenMU/ (origin=MUnique, temiz) Upstream referans — güncel OpenMU (baseline commit b5a0961).
.../AdamuSw/ (origin=gitea.atfatmc.com/atfatmc/AdamuSw, branch main, boş) Ürün repo — CS + remote-NPC burada; image buradan derlenir.

Hedef git kurulumu:

AdamuSw/  origin   = https://gitea.atfatmc.com/atfatmc/AdamuSw.git   (ürün)
          upstream = https://github.com/MUnique/OpenMU.git           (referans)

5. Mimari

CS, OpenMU içinde kalıcı bir alt-sistem olarak kurulur (yaklaşım B). Üç mevcut altyapı yeniden kullanılır:

  • Guild sistemi (GuildServer + Guild.AllianceGuild / Guild.Hostility) → kayıt, alliance, sahiplik.
  • PeriodicTask deseni (PeriodicTaskConfiguration.Timetable + IsItTimeToStart() + PeriodicTaskBasePlugIn.ForceStart()) → zamanlama + admin zorla-başlat.
  • MiniGame parçaları (MiniGameContext: spawn dalgası, terrain değişimi, Destructible NPC'ler, harita oluşturma) → kuşatma savaşı mekaniği. Not: MiniGameContext'i subclass ETMEYECEĞİZ (instance/kısa-ömür modeli CS'nin kalıcı-sahiplik doğasına uymaz); onun parçalarını doğrudan kullanacağız.

Merkezde yeni CastleSiegeContext: uzun ömürlü, kalıcı harita üstünde çalışan, kendi faz state machine'ine sahip servis. Bir periyodik plugin (CastleSiegeEventPlugIn) timetable'a bakıp faz geçişini tetikler.

Faz state machine

Ownership (sahiplik dönemi)
   │  timetable: kayıt açılış
   ▼
Registration ──► guild master NPC'de kayıt, guild mark, ücret, min guild şartları
   │  kayıt kapanış
   ▼
Preparation ──► savunmacı = mevcut sahip; Guardian Statue'lar kurulur
   │  timetable: kuşatma saati
   ▼
Siege ──► kapı kır → kristal/statü yık → taht switch'i tut (contention)
   │  kuşatma süresi doldu
   ▼
Settlement ──► en çok taht tutan guild = yeni sahip; DB'ye yaz
   ▼
Ownership (yeni sahip) ──► döngü başa

6. Bileşenler

6.1 Persistence (yeni veri modeli) — restart'ı atlatması ŞART

  • CastleSiegeState (tekil/kalıcı): mevcut sahip guild, aktif faz, sonraki kayıt/kuşatma zamanı, vergi oranı, biriken vergi.
  • CastleSiegeRegistration: bu döngüdeki guild kayıtları (guild, zaman, guild mark sayısı/rank, alliance).
  • CastleSiegeConfiguration : PeriodicTaskConfiguration: kayıt/kuşatma pencereleri, min guild seviye/üye, kayıt ücreti, vergi alt/üst sınırı, harita/NPC/kapı/kristal/switch tanım referansları.

Karar noktası (plan aşamasında): OpenMU persistence, kaynak-üretilmiş EF modelleri kullanır (DataModel projesi). Yeni kalıcı entity eklemek DataModel + Initialization + EF migration'a dokunmayı gerektirir → touch registry'ye girer.

6.2 Zamanlama / yaşam döngüsü

  • CastleSiegeEventPlugIn — periyodik plugin; timetable'dan kayıt-açılış ve kuşatma zamanlarını okur, CastleSiegeContext'in fazını ilerletir. Admin ForceStart ile fazı zorlar.

6.3 Kuşatma savaşı (Siege fazı, kalıcı CS haritası; client: GMBattleCastle)

  • Kapılar — HP'li Destructible; kırılınca terrain açılır (MiniGame terrain-change).
  • Kristaller / Guardian Statue'lar — yıkılması gereken Destructible'lar.
  • Taht switch'i — ele geçirme noktası; guild switch'i kullanınca "occupier"; contention = tutma süresi / switch sayısı.
  • Siege sırasında PvP açık; yalnızca kayıtlı guild üyeleri haritaya girebilir.

6.4 Sahiplik settlement

  • Kuşatma sonunda kazanan (tahtı en çok/son tutan guild) belirlenir; CastleSiegeState.OwnerGuild'a yazılır, persist edilir; ödüller verilir.

6.5 Sahiplik ödülleri

  • Vergi sistemi — sahip guild Loren Market NPC'lerinde vergi % belirler; alışveriş/store para akışına hook, vergi payı guild havuzuna; sahip birikeni çeker.
  • Sahibe özel av haritası (Gereksinim 2) — kale içi hunting zone; giriş warp'ı guild == owner (ve alliance) kontrolü yapar; özel monster/drop.
  • Guardian Statue'lar — sahip, sonraki kuşatma için savunma statülerini güçlendirebilir.

6.6 Kayıt akışı (tam resmi)

  • Guild master → Guardsman NPC (kayıt penceresinde) → Guild Mark (Sign of Lord'dan craft / drop) → ücret + min guild şartları → attack rank.

6.7 Protokol katmanı

  • İlke: server'ı client'ın beklediği mevcut S6 CS protokolüne uydur; client'a dokunma.
  • Yeni GameLogic/Views/CastleSiege/ view plugin arayüzleri + Network/Packets (ServerToClient) builder'ları + GameServer/MessageHandler (ClientToServer) handler'ları; WSclient.cpp'deki mevcut handler'lara eşle.

6.8 Admin kontrol (Gereksinim 4)

  • AdminPanel sayfası + chat komutları: kayıt/kuşatma zorla başlat-durdur, sahip guild'i zorla ata, config düzenle, kayıt/sahip/vergi görüntüle, CS sıfırla.

7. Entegrasyon & Deployment stratejisi

7.1 Faz 0 — Bootstrap (bir kerelik, CS'den önce)

  1. Temiz upstream OpenMU kaynağını AdamuSw'e kopyala (upstream .git hariç); ilk commit: baseline: OpenMU b5a0961.
  2. AdamuSw'e upstream remote'u ekle (MUnique/OpenMU).
  3. Eski fork'tan (d:/OpenMU/src) remote-NPC değişikliklerini diff'leyip AdamuSw'e port et; // ADAMU-CUSTOM işaretle; touch-registry'ye ekle; commit + Gitea push.
  4. Image'i src/Startup/Dockerfile'dan derle, lokal test → çalıştığını doğrula.
  5. DockerHub'a tag + push; başka sunucuda ayağa kaldır. Stock image'i bırak.

Bu adım memory'deki "MissingMethod tuzağını" kökten çözer (her şey tek kaynaktan birlikte derlenir).

7.2 Merge güvenliği — "upstream merge NPC+CS'yi bozmasın"

  1. Additive-first: CS'nin ~%90'ı yeni dosya/plugin (yeni dosya = sıfır conflict). OpenMU [PlugIn] mimarisi bunu destekler.
  2. Core dokunuşlarını minimize + işaretle: kaçınılmaz core edit'leri // ADAMU-CUSTOM: <neden> blokları ile sar.
  3. Touch registry (§9): dokunulan her core dosyası + neden + değişiklik; merge conflict'te kontrol haritası.
  4. Regresyon testleri: remote-NPC ve CS için unit/entegrasyon testleri; her merge sonrası koşulur → bozulma varsa anında görünür.

7.3 Güncelleme akışı (tekrarlanan)

git fetch upstream
git merge upstream/master        # conflict → ADAMU-CUSTOM + touch registry ile çöz
dotnet test                      # regresyon: NPC + CS yeşil mi?
docker build -f src/Startup/Dockerfile -t <hub>/adamu-openmu:<tag> .
docker push <hub>/adamu-openmu:<tag>
# hedef sunucuda: docker pull + up

8. Hata yönetimi

  • Server restart (herhangi bir faz) → CastleSiegeState'ten (faz + zaman damgaları + sahip + kayıtlar) yükle; timestamp'e göre doğru faza devam et. Sahiplik ve faz restart'ı atlatmalı.
  • Kayıt yok → kuşatma atlanır; mevcut sahip korur (walkover).
  • Beraberlik → mevcut sahip korur.
  • Sahip guild dağılırsa → kale sahipsiz (neutral).

9. Touch registry (core dokunuşları — canlı liste)

Faz 0 ve her fazda güncellenecek. Amaç: upstream merge'lerde çakışma riskini denetlenebilir tutmak.

Dosya Faz Neden Durum
GameLogic/PlayerActions/TalkNpcAction.cs 0b remote-NPC: TalkToNpcByNumberAsync (additive metod) ✅ Uygulandı, // ADAMU-CUSTOM işaretli
GameLogic/GameMap.cs 0b remote-NPC: GetNpcByNumber helper (additive metod) ✅ Uygulandı, // ADAMU-CUSTOM işaretli; test: GameMapTest.GetNpcByNumberFindsSpawnedNpcAsync
GameServer/MessageHandler/TalkNpcHandlerPlugInBase.cs 0b remote-NPC: 0x8000 marker dalı (tek gerçek core-logic dokunuşu) ✅ Uygulandı, // ADAMU-CUSTOM işaretli
GameLogic/Player.cs P3 CS PvP: Siege fazında Valley of Loren'de (map 30) kill izni (IsCastleSiegeBattleActive) ✅ Uygulandı, // ADAMU-CUSTOM
DataModel + Initialization (CS entity'leri) P4 CS persistence (sahiplik/vergi) ⏳ Planlanacak (EF migration gerekir)
(fazlar ilerledikçe eklenecek)

10. Test stratejisi

  • Faz geçişleri için unit test (enjekte edilmiş saat ile zaman-güdümlü).
  • Kazanan belirleme + vergi hesabı unit testleri.
  • Tam döngü entegrasyon testi (sahte guild/oyuncu).
  • Remote-NPC + CS regresyon suit'i (merge güvenliği için).
  • Mobil uçtan uca: config dakikalık → emülatörde tam döngü; client'ın kapı/taht/sahiplik render'ını doğrula.

11. Aşamalı uygulama (alt-projeler)

Faz Kapsam Çıktı
Faz 0 Bootstrap: AdamuSw baseline + upstream remote + remote-NPC port + kendi image + DockerHub Kendi image'imiz ayakta, custom NPC çalışıyor
P1 Veri modeli + persistence + faz state machine + zamanlama + admin start/stop İskelet: fazlar geçer, loglar (savaş yok)
P2 Kayıt akışı (NPC, şartlar, guild mark, ücret) + protokol Guild'ler kayıt olabilir
P3 Kuşatma savaşı (harita, kapı, kristal, taht, PvP, kazanan) + protokol Oynanabilir kuşatma
P4 Sahiplik + vergi + sahibe özel av haritası + Guardian statue + protokol Sahiplik ödülleri
P5 AdminPanel UI + cila + tam mobil uçtan uca Tamamlanmış CS

Her faz kendi spec (gerekirse) → plan → uygulama döngüsünü alır. Sıradaki adım: Faz 0 için detaylı uygulama planı.

12. Plan aşamasında netleştirilecek açık noktalar

  • CS haritasının kesin WorldIndex'i (w_MapHeaders.h / GMBattleCastle'dan doğrula).
  • Mevcut S6 CS paketlerinin kesin formatları (WSclient.cpp handler'larından çıkar).
  • OpenMU DataModel'e yeni kalıcı entity eklemenin kesin mekaniği (source generator + EF migration).
  • Alliance'ın kayıt/sahiplikte tam rolü (tek guild mi, alliance mı sahip olur).
  • Vergi hook'unun para akışında tam yeri (trade / personal store / NPC shop).
Reference in New Issue View Git Blame Copy Permalink