From bd1248511297d6c67c7cdf20267c51085f4a9111 Mon Sep 17 00:00:00 2001
From: devbeni <ballobeni08@gmail.com>
Date: Sun, 14 Dec 2025 10:49:52 +0100
Subject: [PATCH] Add CLAUDE.md documentation for Claude Code
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Provides architecture overview, packet system docs, and common patterns
for future development assistance.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 CLAUDE.md | 104 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 104 insertions(+)
 create mode 100644 CLAUDE.md

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..d7ade77
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,104 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is a **Kingdoms and Castles Multiplayer Mod** that adds multiplayer functionality to the game using:
+- **Riptide Networking** library for low-level networking
+- **Steam P2P** transport for NAT traversal
+- **Harmony** for non-invasive game modification via patches/hooks
+
+## Architecture
+
+### Core Components
+
+| File | Purpose |
+|------|---------|
+| `Main.cs` | Entry point, Harmony patches, all game event hooks |
+| `KCClient.cs` | Client-side networking wrapper around Riptide.Client |
+| `KCServer.cs` | Server-side networking, client management |
+| `KCPlayer.cs` | Player data container (id, steamId, inst, kingdomName) |
+
+### Networking Layer
+
+```
+Riptide.Client/Server
+    └── SteamClient/SteamServer (Steam P2P transport)
+        └── KCClient/KCServer wrappers
+            └── PacketHandler (serialization/routing)
+```
+
+- Port: 7777, Max clients: 25
+- Team ID formula: `clientId * 10 + 2`
+
+### Packet System
+
+Located in `/Packets/`:
+- Base class: `Packet.cs` with `Send()`, `SendToAll()`, `HandlePacketClient()`, `HandlePacketServer()`
+- `PacketHandler.cs` uses reflection for automatic serialization based on property names (alphabetical order)
+- Packet IDs defined in `Enums/Packets.cs`
+
+Key packet ranges:
+- 25-34: Lobby (chat, player list, settings)
+- 70-79: World/building updates
+- 85: Save transfer (chunked)
+- 87-90: Building state, villagers
+
+### State Synchronization
+
+- **Buildings**: Observer pattern in `StateManagement/BuildingState/` - monitors field changes every 100ms, sends updates every 300ms
+- **Villagers**: Event-based sync via Harmony hooks on `VillagerSystem.AddVillager`, `Villager.TeleportTo`
+- **Save/Load**: Custom `MultiplayerSaveContainer` extends `LoadSaveContainer`, stores per-player data
+
+### Harmony Hooks Pattern
+
+All hooks check call stack to prevent infinite loops:
+```csharp
+if (new StackFrame(3).GetMethod().Name.Contains("HandlePacket"))
+    return; // Skip if called by network handler
+```
+
+### Key Dictionaries
+
+```csharp
+Main.kCPlayers        // Dictionary<steamId, KCPlayer>
+Main.clientSteamIds   // Dictionary<clientId, steamId>
+```
+
+## Common Issues & Patterns
+
+### Player Resolution
+```csharp
+Main.GetPlayerByClientID(clientId)  // clientId -> KCPlayer
+Main.GetPlayerByTeamID(teamId)      // teamId -> Player.inst
+Main.GetPlayerByBuilding(building)  // building -> owner Player
+```
+
+### Building Ownership
+Buildings are associated with players via `LandmassOwner.teamId`. Use `building.TeamID()` to determine owner.
+
+### Save Directory
+Multiplayer saves go to: `Application.persistentDataPath + "/Saves/Multiplayer"`
+
+## Directory Structure
+
+```
+/Attributes          - Custom packet attributes
+/Enums              - Packet types, menu states
+/LoadSaveOverrides  - MultiplayerSaveContainer
+/Packets            - All network packets
+/Riptide            - Networking library
+/RiptideSteamTransport - Steam P2P adapter, LobbyManager
+/StateManagement    - Observer pattern for sync
+/ServerLobby        - Lobby UI
+/ServerBrowser      - Server discovery
+/UI                 - Custom UI elements
+```
+
+## Known Architecture Limitations
+
+1. Static `Client`/`Server` instances can cause issues on reconnect
+2. Call stack checking for loop prevention is fragile
+3. No conflict resolution - last-write-wins
+4. Villager sync is event-based only, no continuous state updates