test/Assets/PerfectWorld/Scripts/Task/Doc/TaskSystem_Architecture.md

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
2. System Architecture
3. Data Flow Diagrams
4. Key Components
5. 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

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

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

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

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

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

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

[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

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

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