# Phase 4 Implementation Plan: Networking & Multiplayer

## 🚀 Phase 4 Overview

**Status:** Not Started  
**Priority:** CRITICAL BLOCKER  
**Estimated Effort:** 150-200 hours  
**Complexity:** Very High  
**Impact:** Enables multiplayer functionality (required for all subsequent phases)

---

## ⚠️ Why Phase 4 is Critical

Without networking, **Craft++ cannot support multiplayer** - making it fundamentally incomplete compared to BYOND's multiplayer-first architecture. Phase 4 is the make-or-break phase for the entire project.

**Downstream Dependencies:**
- Phase 5: IDE Features & Debugger (depends on network synchronization)
- Phase 6: Data Persistence (depends on client-server architecture)
- Phase 7: Client Optimization (depends on network efficiency)
- Phase 8+: All advanced features

---

## 🎯 Phase 4 Core Objectives

1. **Establish Client-Server Communication**
   - Implement network protocol (TCP/IP or WebSocket)
   - Establish connection management
   - Handle disconnections gracefully

2. **Synchronize Game State**
   - Network object replication
   - Position/movement synchronization
   - Variable change propagation
   - Animation/effect networking

3. **Implement Remote Procedure Calls (RPC)**
   - Call procs on remote instances
   - Parameter serialization/deserialization
   - Return value handling

4. **Secure Authentication & Sessions**
   - Login system
   - Session management
   - Prevent unauthorized access

---

## 📋 Phase 4 Components

### Component 1: Network Protocol (Est. 30 hours)

**Responsibility:** Define and implement low-level message passing

**Key Classes:**
```csharp
// NetworkProtocol.cs (NEW)
public enum MessageType
{
    Connect,           // Client→Server: Initial connection
    Login,             // Client→Server: Authentication
    Disconnect,        // Bidirectional: Terminate connection
    ObjectSpawned,     // Server→Client: New object appears
    ObjectDespawned,   // Server→Client: Object removed
    ObjectUpdated,     // Server→Client: Object state changed
    VariableChanged,   // Bidirectional: Var update
    ProcCall,          // Bidirectional: RPC invocation
    ProcReturn,        // Bidirectional: RPC result
    Movement,          // Client→Server: Player move input
    Input,             // Client→Server: Player action
    Ping,              // Bidirectional: Latency check
    Chat,              // Bidirectional: Message exchange
}

public class NetworkMessage
{
    public MessageType Type { get; set; }
    public int ClientId { get; set; }
    public Dictionary<string, object> Data { get; set; }
    public byte[] Serialize() { ... }
    public static NetworkMessage Deserialize(byte[] data) { ... }
}

public class NetworkProtocol
{
    public void SendMessage(NetworkMessage msg) { ... }
    public NetworkMessage ReceiveMessage() { ... }
    public void Broadcast(NetworkMessage msg, int? excludeClientId = null) { ... }
}
```

**Required Implementation:**
- Message serialization/deserialization
- Packet framing (handling partial reads)
- Message queuing and ordering
- Compression for large payloads
- CRC checksums for integrity

**Tests to Create:**
- `TestNetworkMessageSerialization` - Verify message encoding/decoding
- `TestNetworkMessageTypes` - All message types serialize correctly
- `TestMessageQueuing` - Messages processed in order
- `TestPacketFragmentation` - Large messages split and reassembled
- `TestCompression` - Payloads compressed correctly

---

### Component 2: Connection Management (Est. 40 hours)

**Responsibility:** Handle connection lifecycle and client state

**Key Classes:**
```csharp
// ConnectionManager.cs (NEW)
public class ClientConnection
{
    public int ClientId { get; }
    public string Username { get; set; }
    public TcpClient Socket { get; set; }
    public bool IsAuthenticated { get; set; }
    public DateTime ConnectedAt { get; set; }
    public DateTime LastHeartbeat { get; set; }
    public int Latency { get; set; }
    
    // Client state
    public CraftValue Mob { get; set; }  // Player character
    public List<CraftValue> Owned { get; set; }  // Owned objects
}

public class ConnectionManager
{
    private Dictionary<int, ClientConnection> _clients = new();
    
    public void AcceptConnection(TcpClient socket) { ... }
    public void AuthenticateClient(int clientId, string username, string password) { ... }
    public void DisconnectClient(int clientId) { ... }
    public void BroadcastToClients(NetworkMessage msg) { ... }
    public void SendToClient(int clientId, NetworkMessage msg) { ... }
    public List<ClientConnection> GetConnectedClients() { ... }
    public void HandleHeartbeat(int clientId) { ... }
    public void DetectDeadConnections() { ... }
}

// ClientService.cs (EXTEND)
public class ClientService
{
    public ClientConnection LocalConnection { get; set; }
    public bool IsConnected { get; set; }
    public string ServerAddress { get; set; }
    public int ServerPort { get; set; }
    
    public void ConnectToServer(string address, int port) { ... }
    public void Disconnect() { ... }
    public void RequestLogin(string username, string password) { ... }
}
```

**Required Implementation:**
- TCP socket management (listening, accepting, connecting)
- Client connection pooling
- Heartbeat/ping mechanism for connection health
- Graceful disconnection handling
- Timeout detection (idle clients)
- Connection retry logic

**Tests to Create:**
- `TestClientConnection` - Accept and manage connections
- `TestAuthentication` - Login/password verification
- `TestHeartbeat` - Heartbeat detection and timeout
- `TestDisconnection` - Clean disconnection handling
- `TestMultipleClients` - Multiple simultaneous connections
- `TestConnectionTimeout` - Detect dead connections

---

### Component 3: Object Replication (Est. 50 hours)

**Responsibility:** Synchronize game objects across network

**Key Classes:**
```csharp
// ObjectReplication.cs (NEW)
public class ReplicatedObject
{
    public int ObjectId { get; set; }
    public string Type { get; set; }  // e.g., "/mob", "/obj/weapon"
    public int OwnerId { get; set; }  // Client who owns this object
    public Dictionary<string, CraftValue> Variables { get; set; }
    public int X { get; set; }
    public int Y { get; set; }
    public int Z { get; set; }
    public bool IsDirty { get; set; }  // Needs sync
}

public class ReplicationManager
{
    private Dictionary<int, ReplicatedObject> _objects = new();
    private int _nextObjectId = 1;
    
    public ReplicatedObject SpawnObject(string type, int ownerId, int x, int y, int z) { ... }
    public void DespawnObject(int objectId) { ... }
    public void UpdateObjectVariable(int objectId, string varName, CraftValue value) { ... }
    public void MoveObject(int objectId, int x, int y, int z) { ... }
    
    // Sync dirty objects to client
    public List<NetworkMessage> GetDeltaUpdates(int clientId) { ... }
    public void MarkDirty(int objectId) { ... }
    public void ClearDirtyFlag(int objectId) { ... }
    
    // Client-side object management
    public CraftValue GetObjectById(int objectId) { ... }
    public List<CraftValue> GetVisibleObjects(int x, int y, int z, int radius) { ... }
}
```

**Required Implementation:**
- Object spawning with unique IDs
- Object state change tracking (dirty flag)
- Delta updates (only sync changed variables)
- Interest management (only sync nearby objects)
- Position reconciliation on movement
- Smooth movement interpolation

**Critical Decisions:**
- **Update Frequency:** 10-30 Hz (typical for MMOs)
- **Visibility Radius:** Configurable per zone
- **Variable Replication:** Selective (not all vars need sync)
- **Movement Model:** Server-authoritative with client prediction

**Tests to Create:**
- `TestObjectSpawning` - Create and track objects
- `TestObjectMovement` - Synchronize position changes
- `TestVariableReplication` - Sync var changes
- `TestDirtyTracking` - Only sync changed objects
- `TestVisibilityManagement` - Only visible objects sent
- `TestDeltaUpdates` - Efficient bandwidth usage

---

### Component 4: Remote Procedure Calls (Est. 40 hours)

**Responsibility:** Execute procedures on remote instances

**Key Classes:**
```csharp
// RemoteProcCall.cs (NEW)
public class ProcCall
{
    public int CallId { get; set; }  // For tracking return values
    public int TargetObjectId { get; set; }
    public string ProcName { get; set; }
    public List<CraftValue> Arguments { get; set; }
    public int CallerClientId { get; set; }
    public bool ExpectsReturn { get; set; }
}

public class ProcCallManager
{
    private Dictionary<int, ProcCall> _pendingCalls = new();
    private int _nextCallId = 1;
    
    public void CallRemoteProc(int targetObjectId, string procName, 
                               List<CraftValue> args, bool expectsReturn) { ... }
    
    public void ExecuteRemoteProcCall(ProcCall call, Interpreter interpreter) { ... }
    
    public void ReturnProcResult(int callId, CraftValue result) { ... }
    
    public void HandleProcReturn(int callId, CraftValue result) { ... }
}

// Interpreter.cs (EXTEND)
public partial class Interpreter
{
    public void CallProcRemote(string procName, List<CraftValue> args) { ... }
}
```

**Required Implementation:**
- RPC serialization (procedure name + arguments)
- Call ID tracking for return values
- Timeout handling for slow/missing responses
- Security validation (proc permissions)
- Error propagation back to caller
- Built-in procs for RPC:
  - `call(object, "proc_name", args...)` - Direct call
  - `call_async(object, "proc_name", args...)` - Fire-and-forget

**Security Considerations:**
- Validate procedure exists before execution
- Check caller permissions
- Prevent access to private procs
- Sandbox remote execution

**Tests to Create:**
- `TestRemoteProcCall` - Basic RPC execution
- `TestProcReturn` - Return values from RPC
- `TestProcTimeout` - Handle slow responses
- `TestProcSecurity` - Permission validation
- `TestProcSerialization` - Complex argument types

---

### Component 5: Authentication & Security (Est. 30 hours)

**Responsibility:** Secure login and session management

**Key Classes:**
```csharp
// AuthenticationService.cs (NEW)
public class User
{
    public int UserId { get; set; }
    public string Username { get; set; }
    public string PasswordHash { get; set; }
    public string Email { get; set; }
    public DateTime CreatedAt { get; set; }
    public DateTime LastLogin { get; set; }
    public bool IsBanned { get; set; }
}

public class AuthenticationService
{
    public bool TryLogin(string username, string password, out User user) { ... }
    public bool TryRegister(string username, string password, string email, out User user) { ... }
    public void LogoutUser(int userId) { ... }
    public bool VerifyPassword(string password, string hash) { ... }
    public string HashPassword(string password) { ... }
}

// SessionManager.cs (NEW)
public class GameSession
{
    public string SessionToken { get; set; }
    public int UserId { get; set; }
    public int ClientId { get; set; }
    public DateTime CreatedAt { get; set; }
    public DateTime LastActivity { get; set; }
    public bool IsActive { get; set; }
}

public class SessionManager
{
    private Dictionary<string, GameSession> _sessions = new();
    
    public string CreateSession(int userId, int clientId) { ... }
    public bool ValidateSession(string token) { ... }
    public void DestroySession(string token) { ... }
    public void UpdateActivity(string token) { ... }
    public List<GameSession> GetSessionsForUser(int userId) { ... }
}
```

**Required Implementation:**
- Password hashing (bcrypt or Argon2)
- Session token generation (secure random)
- Account creation/login
- Account lockout after failed attempts
- Session timeout (30 min default)
- Ban/suspension system

**Tests to Create:**
- `TestLogin` - Valid credentials accepted
- `TestInvalidLogin` - Bad password rejected
- `TestRegister` - New account creation
- `TestSessionCreation` - Valid tokens generated
- `TestSessionTimeout` - Expired sessions invalidated
- `TestAccountLockout` - Too many failures lock account

---

## 📊 Phase 4 Test Suite Structure

Create **Phase4NetworkingTests.cs** (Est. 80+ tests):

```
Phase4NetworkingTests
├── NetworkProtocol (10 tests)
│   ├── TestMessageSerialization
│   ├── TestMessageDeserialization
│   ├── TestMessageTypes
│   ├── TestPacketFragmentation
│   ├── TestMessageCompression
│   └── [5 more]
│
├── ConnectionManagement (12 tests)
│   ├── TestClientConnection
│   ├── TestAuthentication
│   ├── TestHeartbeat
│   ├── TestDisconnection
│   ├── TestMultipleClients
│   └── [7 more]
│
├── ObjectReplication (15 tests)
│   ├── TestObjectSpawning
│   ├── TestObjectMovement
│   ├── TestVariableReplication
│   ├── TestDirtyTracking
│   ├── TestVisibilityManagement
│   └── [10 more]
│
├── RemoteProcCalls (12 tests)
│   ├── TestRemoteProcCall
│   ├── TestProcReturn
│   ├── TestProcTimeout
│   ├── TestProcSecurity
│   └── [8 more]
│
└── Authentication (10 tests)
    ├── TestLogin
    ├── TestInvalidLogin
    ├── TestRegister
    ├── TestSessionCreation
    ├── TestSessionTimeout
    └── [5 more]
```

**Target:** 80-90 tests, all passing before Phase 4 completion

---

## 🎮 Example: Multiplayer Mob Movement

This demonstrates how Phase 4 components work together:

```csharp
// Client: Player moves mob
input_hub.Up()  // Player pressed Up arrow
→ Interpreter.CallProcLocal(localMob, "Move", new(0, 1, 0))
→ localMob X/Y updated locally (client prediction)
→ NetworkManager.SendMovement(localMob.ObjectId, newX, newY)

// Server: Validates and replicates
→ ConnectionManager receives Movement message from clientId
→ ReplicationManager.MoveObject(mobId, newX, newY)
→ Server broadcasts to nearby clients:
   - ObjectUpdated message with new position
   - Animation change (step animation)

// Other Clients: Receive and display
→ NetworkManager.ReceiveMessage() gets ObjectUpdated
→ ReplicationManager.UpdateObjectVariable(mobId, "pixel_x", value)
→ DreamSeekerWindow.Render() shows mob at new position
→ Animation plays walk cycle
```

---

## 🔄 Network Update Loop

```
Server Tick (10 Hz)
├─ Process incoming messages
│  ├─ Player input (movement, actions)
│  ├─ RPC calls
│  └─ Connection heartbeats
├─ Update world state
│  ├─ Process spawns
│  ├─ Process animations
│  └─ Process physics
├─ Replicate to clients
│  ├─ Gather dirty objects
│  ├─ Perform visibility culling
│  ├─ Compress updates
│  └─ Send packets
└─ Store to database (every 60 sec)

Client Tick (60 Hz)
├─ Receive network messages
├─ Update local object state
├─ Apply client prediction
├─ Render scene
└─ Send player input
```

---

## 🏆 Phase 4 Success Criteria

- [x] Network protocol fully specified
- [ ] Connection manager implementation (50 hours)
- [ ] Object replication system (50 hours)
- [ ] Remote procedure calls (40 hours)
- [ ] Authentication & security (30 hours)
- [ ] 80+ networking tests passing (100%)
- [ ] Multi-client test environment working
- [ ] No breaking changes to Phase 1-3
- [ ] Network latency < 100ms LAN
- [ ] Supports 50+ concurrent clients (per server)

---

## 💾 Integration Checklist

Before Phase 4 completion, verify:
- [ ] ClientService extended for network I/O
- [ ] WorldRegistry works with network objects
- [ ] Interpreter supports remote proc calls
- [ ] CraftValue serializes for network transmission
- [ ] DreamSeekerWindow updates on network messages
- [ ] Parser/Lexer unchanged (no breaking changes)

---

## ⏰ Detailed Timeline Estimate

| Component | Subtasks | Estimated Hours |
|-----------|----------|-----------------|
| Protocol | Design, serialize, tests | 30 |
| Connections | Accept, auth, heartbeat, tests | 40 |
| Replication | Spawning, state sync, culling, tests | 50 |
| RPC | Call execution, returns, security, tests | 40 |
| Auth | Login, hashing, sessions, tests | 30 |
| **Total Phase 4** | **5 components** | **190 hours** |

**Recommended Breakdown:**
- Week 1-2: Protocol + Connections (70 hrs)
- Week 3-4: Replication (50 hrs)
- Week 5: RPC (40 hrs)
- Week 6: Authentication (30 hrs)
- Testing & Integration (continuous)

---

## 🎯 Next Steps After Phase 4

Once Phase 4 networking is complete:

**Phase 5:** IDE Features & Debugger (80 hours)
- Syntax highlighting improvements
- Code completion enhancement
- Debugger with breakpoints/stepping
- Network traffic inspector

**Phase 6:** Data Persistence (60 hours)
- World saving/loading
- Character persistence
- Database integration
- Save file format

**Phase 7:** Client Optimization (40 hours)
- Viewport culling
- Sprite batching
- Network bandwidth reduction
- Rendering performance

---

## 📝 Notes & Considerations

1. **Scalability:** Design for 50-100+ concurrent clients from the start
2. **Latency:** Accept 50-200ms network lag; use client prediction
3. **Security:** Never trust client input; validate all RPC calls server-side
4. **Persistence:** Network = client connection; separate from save/load
5. **Testing:** Must test with multiple clients simultaneously
6. **Backwards Compatibility:** Phase 1-3 must remain unaffected

---

**Status:** Ready for implementation  
**Prerequisite:** Phase 1, 2, 3 complete ✅  
**Blocker Level:** CRITICAL - No multiplayer without this  
**Recommendation:** Prioritize Phase 4 completion immediately