Guide Understanding package structure from UI

[xxxgugaxx]

In this guide we will cover how to understand and implement the packages belonging to the Lineage 2 UI. More specifically the Essence version UI.

Required UTPT (Unreal Tournament Package Tool) : https://github.com/l2jsourcecode/ut-package-tool
File : InterfaceClassic.U
 

The packages are embedded into the interface, specifically located in the InterfaceClassic.u file. Some key classes include:

• UIPacket.uc (defines package structure)
• UIProtocol.uc (defines package opcode)

 

The packages are split into two main types:

• Client to Server (prefix: C)
• Server to Client (prefix: S)

For example, in the UIProtocol class:

 

const C_EX_COSTUME_LOCK = 573; // packet from client to server
const S_EX_COSTUME_LOCK = 785; // packet from server to client

 

We’ll use this package as a case study to delve deeper.

Understanding Client to Server Packets Let's examine a packet from the client with an opcode of 573. On the server side, opcodes are converted into hexadecimal values using a formula:

opcode - C_MAX

 

where C_MAX is an opcode defined in UIProtocol. Recently, C_MAX has been set to 209.
For instance:

573 - 209 = 364 364 -> hex = 16C

This hexadecimal value (16C) corresponds to the opcode for the Java class.
Understanding Server to Client Packets
For server packets, we also use hexadecimal conversion but with a different opcode:

S_MAX = 255
S_MAX is applied to packages with an opcode above 255. For values below this, simply convert the number to hex.



For example:

const S_EX_COSTUME_LOCK = 785; 785 - 255 = 530 530 -> hex = 212 = 0xFE:0x212

Here, 0xFE represents S_MAX.



Packet Structure


Finally, let’s look at the packet structure.

Open UIPacket.uc and locate the C_EX_COSTUME_LOCK to examine its structure in detail.
 

struct _C_EX_COSTUME_LOCK
{
    var int nCostumeId;
    var int nLockState;
};

 

We observe two integer variables, representing the structure of the package transmitted to the server. By continuing our search within this file, we find the following code:

 

static function bool Encode_C_EX_COSTUME_LOCK(out array<byte> stream, _C_EX_COSTUME_LOCK packet)
{
    if(!EncodeInt(stream, packet.nCostumeId)) {
        return false;
    }
    if(!EncodeChar(stream, packet.nLockState)) {
        return false;
    }
    return true;
}

 

This function encodes the packet structure for transmission. As discussed earlier, the data types within the packet are crucial. Specifically:

 

EncodeInt corresponds to an integer. EncodeChar is treated as a short in Java, typically read using readC, while readD is used for EncodeInt. Having examined the client-to-server packet structure, let's now explore the structure expected by the client from the server. The process is similar. We locate _S_EX_COSTUME_LOCK within UIPacket:

 

 

struct _S_EX_COSTUME_LOCK
{
    var byte bResult;
    var int nCostumeId;
    var int nLockState;
};

 

Data Decryption

The corresponding decryption function is:

 

static function bool Decode_S_EX_COSTUME_LOCK(out _S_EX_COSTUME_LOCK packet)
{
    if(!DecodeBool(packet.bResult)) {
        return false;
    }
    if(!DecodeInt(packet.nCostumeId)) {
        return false;
    }
    if(!DecodeChar(packet.nLockState)) {
        return false;
    }
    return true;
}

 

Here, the variables are decoded as follows:

 

bResult is decoded as a Bool.

nCostumeId is decoded as an Int.

nLockState is decoded as a Char.

 

This consistent approach to encoding and decoding ensures reliable data transmission between the client and server.

Example usage : 
https://imgur.com/a/zVZHVzq

Credits : L2j West Coast Custom ( https://discord.gg/n2c8meMN )