2nd/10_Wiki/Topics/Frontend/Kingdom vs. Kingdom Events (KvK).md

---
id: wiki-2026-0508-kingdom-vs-kingdom-events-kvk
title: Kingdom vs. Kingdom Events (KvK)
category: 10_Wiki/Topics
status: verified
canonical_id: self
aliases: [KvK, Kingdom vs Kingdom, Cross-Kingdom Event]
duplicate_of: none
source_trust_level: B
confidence_score: 0.85
verification_status: applied
tags: [game, mmo, rok, event, server-architecture]
raw_sources: []
last_reinforced: 2026-05-10
github_commit: pending
tech_stack:
  language: TypeScript
  framework: GameServer
---

# Kingdom vs. Kingdom Events (KvK)

## 매 한 줄
> **"매 KvK 는 multiple game shards (kingdoms) 가 same world map 에서 PvP 경쟁하는 cross-shard event"**. Rise of Kingdoms (Lilith), Lords Mobile (IGG), Evony 등 4X mobile MMO 의 핵심 monetization driver. 매 frontend 입장에서 cross-kingdom matching, real-time map sync, leaderboard 가 challenge.

## 매 핵심

### 매 매칭 단계
- **Pre-KvK**: 매 power matchmaking — 매 비슷한 power 의 kingdoms 매칭.
- **Lost Kingdom (LK)** / Pass 1: 매 kingdoms 가 새 map 에 spawn.
- **Main KvK (Pass 2-3)**: 매 holy site / pass / altar 점령.
- **Post-KvK**: 매 reward distribution, kingdom power recompute.

### 매 frontend challenge
- **Map sync**: 매 1000+ players concurrent → 매 viewport-based delta sync.
- **Leaderboard**: 매 cross-shard aggregation — 매 5-min cache.
- **Chat**: 매 kingdom-only / alliance-only / cross-kingdom 매 channel 분리.
- **Replay**: 매 battle replay — 매 server-authoritative state log.

### 매 응용
1. Rise of Kingdoms — 매 8 kingdom matchup, 70-day season.
2. Lords Mobile Kingdom Vs Kingdom.
3. Evony Server War.
4. Top War: Battle Game — 매 SvS (Server vs Server).

## 💻 패턴

### Cross-shard matchmaking
```typescript
// 매 power-bracket 매칭
async function matchKvK(season: number) {
  const kingdoms = await db.kingdoms
    .where("season", season)
    .where("optedIn", true)
    .orderBy("totalPower", "desc")
    .get();

  // 매 8 kingdoms / bracket
  const brackets: Kingdom[][] = [];
  for (let i = 0; i < kingdoms.length; i += 8) {
    brackets.push(kingdoms.slice(i, i + 8));
  }
  return brackets;
}
```

### Viewport-based map sync (frontend)
```typescript
class KvKMap {
  private wsUrl = "wss://kvk.game/v1/map";

  subscribe(viewport: Bounds) {
    this.ws.send({
      op: "subscribe",
      bbox: viewport,           // 매 viewport bbox 만 sync
      lod: viewport.zoom < 5 ? "tile" : "unit",
    });
  }

  onMessage({ delta }: { delta: TileDelta[] }) {
    delta.forEach((d) => this.applyTile(d));
  }
}
```

### Leaderboard cache pattern
```typescript
// 매 cross-shard aggregation 비쌈 → 매 Redis sorted set + 5min TTL
async function getKvKLeaderboard(seasonId: string) {
  const cached = await redis.get(`kvk:lb:${seasonId}`);
  if (cached) return JSON.parse(cached);

  const data = await aggregateAcrossShards(seasonId); // 매 fan-out
  await redis.setex(`kvk:lb:${seasonId}`, 300, JSON.stringify(data));
  return data;
}
```

### Real-time troop march UI
```tsx
function MarchPath({ march }: { march: MarchEvent }) {
  const [progress, setProgress] = useState(0);
  useEffect(() => {
    const start = march.startedAt;
    const dur = march.duration;
    const id = requestAnimationFrame(function tick() {
      setProgress(Math.min(1, (Date.now() - start) / dur));
      if (Date.now() < start + dur) requestAnimationFrame(tick);
    });
    return () => cancelAnimationFrame(id);
  }, [march]);

  return <Line from={march.from} to={march.to} t={progress} />;
}
```

### Holy site capture timer (server-authoritative)
```typescript
interface HolySiteState {
  ownerKingdom: number | null;
  captureProgress: number; // 0-1
  contestedBy: number[];
  lastUpdate: number; // server timestamp
}

// 매 client 는 server time 만 신뢰
function renderProgress(state: HolySiteState, serverTime: number) {
  const elapsed = serverTime - state.lastUpdate;
  return state.captureProgress + (elapsed / CAPTURE_DURATION);
}
```

## 매 결정 기준
| Aspect | Approach |
|---|---|
| Matchmaking | Power-bracket, opt-in |
| Map sync | Viewport delta (not full snapshot) |
| Leaderboard | Cached aggregation, 5min TTL |
| Anti-cheat | Server-authoritative timer + replay log |
| Chat | Channel separation, rate limit per kingdom |

**기본값**: server-authoritative state, viewport-based delta, Redis-cached leaderboard.

## 🔗 Graph
- 응용: [[Rise of Kingdoms]]

## 🤖 LLM 활용
**언제**: KvK frontend 설계, cross-shard matchmaking, leaderboard cache 설계.
**언제 X**: 매 single-shard PvP — 매 별도 패턴.

## ❌ 안티패턴
- **Full map snapshot per tick**: 매 BW 폭증 — 매 viewport delta 가 정답.
- **Client-side capture timer**: 매 cheat 가능 — 매 server-authoritative.
- **Real-time leaderboard**: 매 fan-out 비용 → 매 5min cache 충분.

## 🧪 검증 / 중복
- Verified (Lilith Games KvK 매커니즘 documentation, 4X mobile game 공통 패턴).
- 신뢰도 B (game-specific).

## 🕓 Changelog
| 날짜 | 변경 |
|---|---|
| 2026-05-08 | Phase 1 |
| 2026-05-10 | Manual cleanup — KvK matchmaking + frontend sync 패턴 |