# Task System High-Level Architecture Document

This document provides a high-level overview of the Task System architecture, including communication protocols, data flow, and system components.

---

## Table of Contents

1. [Protocol Communication](#protocol-communication)
2. [System Architecture](#system-architecture)
3. [Data Flow Diagrams](#data-flow-diagrams)
4. [Key Components](#key-components)
5. [Message Types](#message-types)

---

## Protocol Communication

### Primary Protocol Name

The Task System uses the following protocol for client-server communication:

- **Protocol Name**: `c2s_CmdTaskNotify` (Client to Server)
- **Command ID**: `TASK_NOTIFY` (value: 70) in `CommandID` enum
- **Server Response**: Various `TASK_SVR_NOTIFY_*` notification messages

### Protocol Implementation

- **Client Side**: `UnityGameSession.c2s_CmdTaskNotify(byte[] pBuf, uint sz)`
- **Server Side**: `GameSession.c2s_SendCmdTaskNotify(byte[] pData, uint dwDataSize)`
- **Base Structure**: `task_notify_base` containing `reason` (byte) and `task` (ushort)

---

## System Architecture

### High-Level Component Diagram

```mermaid
graph TB
    subgraph Client["Client Side"]
        UI[Task UI Components]
        TaskClient[TaskClient]
        TaskInterface[CECTaskInterface]
        TaskTemplMan[ATaskTemplMan]
        ActiveList[ActiveTaskList]
        FinishedList[FinishedTaskList]
    end
    
    subgraph Network["Network Layer"]
        UnitySession[UnityGameSession]
        GameSession[GameSession]
    end
    
    subgraph Server["Server Side"]
        TaskServer[TaskServer]
        ServerLogic[Server Task Logic]
    end
    
    UI --> TaskClient
    TaskClient --> TaskInterface
    TaskInterface --> TaskTemplMan
    TaskInterface --> ActiveList
    TaskInterface --> FinishedList
    
    TaskClient --> UnitySession
    UnitySession --> GameSession
    GameSession -->|c2s_CmdTaskNotify| ServerLogic
    ServerLogic --> TaskServer
    ServerLogic -->|TASK_SVR_NOTIFY_*| GameSession
    GameSession --> UnitySession
    UnitySession --> TaskClient
```

---

## Data Flow Diagrams

### 1. Task Accept Flow

```mermaid
sequenceDiagram
    participant UI as Task UI
    participant TC as TaskClient
    participant TI as TaskInterface
    participant NS as Network Session
    participant S as Server
    
    UI->>TC: User clicks Accept Task
    TC->>TI: CanDeliverTask(taskId)
    TI->>TI: CheckPrerequisite()
    alt Prerequisites Met
        TC->>NS: c2s_CmdTaskNotify(TASK_CLT_NOTIFY_MANUAL_TRIG)
        NS->>S: Send notification
        S->>S: Validate & Process
        S->>NS: TASK_SVR_NOTIFY_NEW
        NS->>TC: OnServerNotify()
        TC->>TI: Update ActiveTaskList
        TC->>UI: UpdateTaskUI()
    else Prerequisites Failed
        TC->>UI: Show Error Message
    end
```

### 2. Task Completion Flow

```mermaid
sequenceDiagram
    participant Game as Game Logic
    participant TC as TaskClient
    participant TI as TaskInterface
    participant NS as Network Session
    participant S as Server
    
    Game->>TC: OnTaskCheckStatus()
    TC->>TI: Check task conditions
    TI->>TI: CanFinishTask()
    TI->>TI: RecursiveCheckAward()
    
    alt Task Can Complete
        TC->>NS: c2s_CmdTaskNotify(TASK_CLT_NOTIFY_CHECK_FINISH)
        NS->>S: Send completion request
        S->>S: Validate completion
        S->>S: Process awards
        S->>NS: TASK_SVR_NOTIFY_COMPLETE
        NS->>TC: OnServerNotify()
        TC->>TI: Update task state
        TC->>TI: Apply awards
        TC->>UI: UpdateTaskUI()
    end
```

### 3. Task Give Up Flow

```mermaid
sequenceDiagram
    participant UI as Task UI
    participant TC as TaskClient
    participant TI as TaskInterface
    participant NS as Network Session
    participant S as Server
    
    UI->>TC: User clicks Give Up
    TC->>TI: GiveUpTask(taskId)
    TC->>NS: c2s_CmdTaskNotify(TASK_CLT_NOTIFY_CHECK_GIVEUP)
    NS->>S: Send give up request
    S->>S: Validate give up
    S->>NS: TASK_SVR_NOTIFY_GIVE_UP
    NS->>TC: OnServerNotify()
    TC->>TI: Remove from ActiveTaskList
    TC->>UI: UpdateTaskUI()
```

### 4. Task Progress Update Flow

```mermaid
sequenceDiagram
    participant Game as Game Logic
    participant TC as TaskClient
    participant TI as TaskInterface
    participant NS as Network Session
    participant S as Server
    
    Game->>Game: Monster killed / Item collected
    Game->>S: Progress update (via game protocol)
    S->>S: Update task progress
    S->>NS: TASK_SVR_NOTIFY_MONSTER_KILLED
    S->>NS: TASK_SVR_NOTIFY_PLAYER_KILLED
    NS->>TC: OnServerNotify()
    TC->>TI: Update ActiveTaskEntry
    TC->>UI: UpdateTaskUI()
```

### 5. Task Initialization Flow

```mermaid
sequenceDiagram
    participant Game as Game Run
    participant TI as TaskInterface
    participant TM as TaskTemplMan
    participant NS as Network Session
    participant S as Server
    
    Game->>TI: Init(activeList, finishedList, ...)
    TI->>TM: LoadTasksFromPack()
    TI->>TI: InitActiveTaskList()
    TI->>NS: Request dynamic tasks time mark
    NS->>S: TASK_CLT_NOTIFY_DYN_TIMEMARK
    S->>NS: TASK_SVR_NOTIFY_DYN_TIME_MARK
    NS->>TI: OnServerNotify()
    TI->>NS: Request storage tasks
    NS->>S: TASK_CLT_NOTIFY_STORAGE
    S->>NS: TASK_SVR_NOTIFY_STORAGE
    NS->>TI: OnServerNotify()
```

---

## Key Components

### Client-Side Components

#### 1. **TaskInterface** (`CECTaskInterface`)
- **Purpose**: Main interface for task operations
- **Key Methods**:
  - `Init()`: Initialize task system with data buffers
  - `GetTaskStateInfo()`: Get current task state
  - `CanDeliverTask()`: Check if task can be accepted
  - `NotifyServer()`: Send notifications to server

#### 2. **TaskClient**
- **Purpose**: Client-side task logic and status checking
- **Key Methods**:
  - `OnTaskCheckStatus()`: Periodic task status validation
  - `OnServerNotify()`: Handle server notifications
  - `_notify_svr()`: Send client notifications to server

#### 3. **ATaskTemplMan**
- **Purpose**: Task template manager
- **Key Methods**:
  - `LoadTasksFromPack()`: Load task templates from data files
  - `GetTaskTemplByID()`: Retrieve task template by ID
  - `GetTopTaskByID()`: Get top-level task template

#### 4. **ActiveTaskList**
- **Purpose**: Manages currently active tasks
- **Structure**: Contains array of `ActiveTaskEntry` objects
- **Key Fields**:
  - `m_uTaskCount`: Number of active tasks
  - `m_TaskEntries[]`: Array of task entries

#### 5. **FinishedTaskList**
- **Purpose**: Tracks completed tasks
- **Structure**: Contains list of finished task IDs and metadata

### Server-Side Components

#### 1. **TaskServer**
- **Purpose**: Server-side task operations
- **Key Methods**:
  - `OnTaskGiveUpOneTask()`: Handle task abandonment

---

## Message Types

### Client-to-Server Notifications (`TASK_CLT_NOTIFY_*`)

| Constant | Value | Description |
|----------|-------|-------------|
| `TASK_CLT_NOTIFY_CHECK_FINISH` | 1 | Request task completion check |
| `TASK_CLT_NOTIFY_CHECK_GIVEUP` | 2 | Request task give up |
| `TASK_CLT_NOTIFY_REACH_SITE` | 3 | Notify reached target location |
| `TASK_CLT_NOTIFY_AUTO_DELV` | 4 | Auto-deliver task |
| `TASK_CLT_NOTIFY_MANUAL_TRIG` | 5 | Manual task trigger (accept) |
| `TASK_CLT_NOTIFY_FORCE_GIVEUP` | 6 | Force give up task |
| `TASK_CLT_NOTIFY_DYN_TIMEMARK` | 7 | Request dynamic tasks time mark |
| `TASK_CLT_NOTIFY_DYN_DATA` | 8 | Request dynamic tasks data |
| `TASK_CLT_NOTIFY_SPECIAL_AWARD` | 9 | Request special award info |
| `TASK_CLT_NOTIFY_LEAVE_SITE` | 10 | Notify left target location |
| `TASK_CLT_NOTIFY_PQ_CHECK_INIT` | 11 | Public Quest check init |
| `TASK_CLT_NOTIFY_STORAGE` | 12 | Request storage tasks |
| `TASK_CLT_NOTIFY_REQUEST_TREASURE_INDEX` | 14 | Request treasure map index |
| `TASK_CLT_NOTIFY_15DAYS_NOLOGIN` | 15 | 15 days no login notification |
| `TASK_CLT_NOTIFY_SPECIAL_AWARD_MASK` | 16 | Special award mask |
| `TASK_CLT_NOTIFY_TITLE_TASK` | 17 | Title task notification |
| `TASK_CLT_NOTIFY_CHOOSE_AWARD` | 18 | Choose award notification |
| `TASK_CLT_NOTIFY_BUY_TOKENSHOP_ITEM` | 20 | Buy token shop item |
| `TASK_CLT_NOTIFY_FINISH_TASK_BY_WORLD_CONTRIBUTION` | 21 | Finish task by world contribution |
| `TASK_CLT_NOTIFY_RM_FINISH_TASK` | 150 | Remove finished task |

### Server-to-Client Notifications (`TASK_SVR_NOTIFY_*`)

| Constant | Value | Description |
|----------|-------|-------------|
| `TASK_SVR_NOTIFY_NEW` | 1 | New task assigned |
| `TASK_SVR_NOTIFY_COMPLETE` | 2 | Task completed |
| `TASK_SVR_NOTIFY_GIVE_UP` | 3 | Task given up |
| `TASK_SVR_NOTIFY_MONSTER_KILLED` | 4 | Monster killed (progress update) |
| `TASK_SVR_NOTIFY_FINISHED` | 5 | Task finished |
| `TASK_SVR_NOTIFY_ERROR_CODE` | 6 | Task error code |
| `TASK_SVR_NOTIFY_FORGET_SKILL` | 7 | Forget skill notification |
| `TASK_SVR_NOTIFY_DYN_TIME_MARK` | 8 | Dynamic tasks time mark |
| `TASK_SVR_NOTIFY_DYN_DATA` | 9 | Dynamic tasks data |
| `TASK_SVR_NOTIFY_SPECIAL_AWARD` | 10 | Special award notification |
| `TASK_SVR_NOTIFY_STORAGE` | 11 | Storage tasks data |
| `TASK_SVR_NOTIFY_DIS_GLOBAL_VAL` | 12 | Disable global value |
| `TASK_SVR_NOTIFY_TREASURE_MAP` | 13 | Treasure map notification |
| `TASK_SVR_NOTIFY_SET_TASK_LIMIT` | 14 | Set task limit |
| `TASK_SVR_NOTIFY_PLAYER_KILLED` | 15 | Player killed (progress update) |

---

## Data Structures

### Task Notification Base Structure

```csharp
[StructLayout(LayoutKind.Sequential, Pack = 1)]
public struct task_notify_base
{
    public byte reason;    // Notification reason (TASK_CLT_NOTIFY_* or TASK_SVR_NOTIFY_*)
    public ushort task;    // Task ID
}
```

### Active Task Entry

```csharp
public class ActiveTaskEntry : TASK_ENTRY_FIXED_DATA
{
    public ushort m_ID;              // Task ID
    public char m_ParentIndex;       // Parent node index
    public char m_ChildIndex;         // Child node index
    public uint m_ulTaskTime;         // Task start timestamp
    public uint m_ulTemplAddr;       // Template address (ID in C#)
    public ushort[] m_wMonsterNum;   // Monster kill counts
    // ... additional fields
}
```

---

## Task State Machine

```mermaid
stateDiagram-v2
    [*] --> Available: Task Template Loaded
    Available --> Active: Accept Task (TASK_CLT_NOTIFY_MANUAL_TRIG)
    Active --> InProgress: Task Started
    InProgress --> Completed: Conditions Met (TASK_CLT_NOTIFY_CHECK_FINISH)
    InProgress --> Failed: Timeout / Fail Condition
    InProgress --> Abandoned: Give Up (TASK_CLT_NOTIFY_CHECK_GIVEUP)
    Completed --> Finished: Awards Applied (TASK_SVR_NOTIFY_COMPLETE)
    Failed --> [*]
    Abandoned --> [*]
    Finished --> [*]
```

---

## Error Codes

The system uses various error codes defined in `TaskInterfaceConstants`:

- `TASK_PREREQU_FAIL_*`: Prerequisite check failures (1-66)
- `TASK_AWARD_FAIL_*`: Award processing failures (150-160)

Common error codes:
- `TASK_PREREQU_FAIL_BELOW_LEVEL`: Player level too low
- `TASK_PREREQU_FAIL_NO_SPACE`: No space for new task
- `TASK_PREREQU_FAIL_PREV_TASK`: Previous task not completed
- `TASK_AWARD_FAIL_GIVEN_ITEM`: Item award failed

---

## Notes

1. **Version Checking**: The system includes version checking for task list compatibility
2. **Dynamic Tasks**: Supports dynamic tasks that can be updated at runtime
3. **Storage Tasks**: Library/storage tasks system for task management
4. **Public Quests**: Special quest type (PQ) with shared state
5. **Task Templates**: Tasks are defined in data files (`tasks.data`, `task_npc.data`, `dyn_tasks.data`)

---

## References

- `TaskInterface.cs`: Core task interface definition
- `CECTaskInterface.cs`: Client implementation of task interface
- `TaskClient.cs`: Client-side task logic
- `TaskServer.cs`: Server-side task operations
- `TaskTempl.cs`: Task template constants and structures
- `TaskProcess.cs`: Task entry and list structures