UpdateMask

An UpdateMask is a variable length way of sending known fields to the client. It is represented by a byte mask that decides which fields are sent afterwards.

Representation

The UpdateMask starts with a single u8 that decides how many u32 mask blocks will follow. The bit pattern in these mask blocks determine how many additional u32s of data will follow and how to interpret that data.

Examples

The absolute minimum amount of fields that need to be set to log a player into the world are:

• OBJECT_GUID, an Object field.
• OBJECT_TYPE, an Object field.
• UNIT_HEALTH, a Unit field.
• UNIT_BYTES_0, a Unit field.

To find out how many mask blocks we need to send we take the highest offset field (UNIT_BYTES_0 with 36) and divide it by the amount of bits in a u32 and rounding up. This gives us 2 mask blocks that we need to send.

To figure out which bits must be set on the mask blocks we look up the offset and sizes for our fields. A size of 1 means that only the bit at the offset should be set. A size of 2 means that the bit at the offset and the bit at the offset + 1 should be set, and so on.

Realistically you will have to store the mask blocks in an array of u32s. The correct index and bit position can then be found by dividing to find the index, and modulus to find the bit position within that index.

For UNIT_BYTES_0 with an offset of 36, this means that our index and bit position is:

index = 36 / 32 = 1
bit = 36 % 32 = 4

We do this for every field.

We then send, in order:

1. A u8 with the amount of mask bytes.
2. The mask bytes as u32s.
3. The data values as u32s.

Examples

The following Python example uses the asyncio module. Additionally read_int is a function that reads a certain amount of bytes and returns it as an integer. So read_int(reader, 1) would return a u8 and read_int(reader, 4) would return a u32.

The dict[int, int] is a dictionary of integers, also called a hash map. The keys are the offsets defined below, and the values are u32 data values.

The write function uses Python's struct module to pack the data into a byte array. The reference for struct lists the different format characters used.

The Python code below does not have the best API; users will have to fill out the dict using the offsets defined as constants without any type safety, merging of fields for Guids, or splitting of fields into smaller types. When designing your own UpdateMask type consider what API it allows you to expose.

class UpdateMask:
    fields: dict[int, int]

    @staticmethod
    async def read(reader: asyncio.StreamReader):
        amount_of_blocks = await read_int(reader, 1)

        blocks = []
        for _ in range(0, amount_of_blocks):
            blocks.append(await read_int(reader, 4))

        fields = {}
        for block_index, block in enumerate(blocks):
            for bit in range(0, 32):
                if block & 1 << bit:
                    value = await read_int(reader, 4)
                    key = block_index * 32 + bit
                    fields[key] = value

        return UpdateMask(fields=fields)

    def write(self, fmt, data):
        highest_key = max(self.fields)
        amount_of_blocks = highest_key // 32
        if highest_key % 32 != 0:
            amount_of_blocks += 1

        fmt += 'B'
        data.append(amount_of_blocks)

        blocks = [0] * amount_of_blocks

        for key in self.fields:
            block = key // 32
            index = key % 32
            blocks[block] |= 1 << index

        fmt += f'{len(blocks)}I'
        data.extend(blocks)

        for key in sorted(self.fields):
            fmt += 'I'
            data.append(self.fields[key])

        return fmt, data

    def size(self):
        highest_key = max(self.fields)
        amount_of_blocks = highest_key // 32

        extra = highest_key % 32
        if extra != 0:
            extra = 1
        else:
            extra = 0

        return 1 + (extra + amount_of_blocks + len(self.fields)) * 4

Lookup Table

Version 1.12

Taken from vmangos with some modifications.

Fields that all objects have:

Fields that all items have:

Fields that all containers have:

Fields that all units have:

Fields that all players have:

Fields that all gameobjects have:

Fields that all dynamicobjects have:

Fields that all corpses have:

Version 2.4.3

Taken from mangosone with some modifications.

Fields that all objects have:

Fields that all items have:

Fields that all containers have:

Fields that all units have:

Fields that all players have:

Fields that all gameobjects have:

Fields that all dynamicobjects have:

Fields that all corpses have:

Version 3.3.5

Taken from ArcEmu with some modifications.

Fields that all objects have:

Fields that all items have:

Fields that all containers have:

Fields that all units have:

Fields that all players have:

Fields that all gameobjects have:

Fields that all dynamicobjects have:

Fields that all corpses have: