Plasma messages

plNetMsgGameMessage and its subclasses contain another kind of message, plMessage. These messages are mainly used locally by the clients, but can also be propagated over the network.

Almost all plMessages sent over the network originate from a client, with the server only relaying the messages from the sender to any number of receiving clients. In some cases, the server also sends plMessages of its own though, e. g. when responding to a plNetMsgTestAndSet.

Like with plNetMessage, the different plMessage subclasses are identified by their plCreatable class index and can often be sent both from client to server and from server to client.

Below is an overview of the plMessage class hierarchy in the open-sourced client code, along with the corresponding class indices and the intended message direction. Classes marked as “abstract” are only used as base classes — a message should never be a direct instance of one of these classes, only of one of their non-abstract subclasses.

Note

This is not a complete list. The open-sourced client code contains around 200 different plMessage subclasses, many of which are either completely unused or only used locally and never propagated over the network.

Eventually, it should contain all plMessage subclasses that are expected to be sent over the network. For the moment, it only covers an incomplete subset of messages that are commonly seen during normal gameplay.

plMessage = 0x0202 = 514 (abstract)
- plLoadCloneMsg = 0x0253 = 595
  - plLoadAvatarMsg = 0x03b1 = 945
- plEnableMsg = 0x0254 = 596
- plServerReplyMsg = 0x026f = 623
- plMessageWithCallbacks = 0x0283 = 643 (abstract)
  - plAnimCmdMsg = 0x0206 = 518
- plAvatarMsg = 0x0297 = 663 (abstract)
  - plAvTaskMsg = 0x0298 = 664
    - plAvSeekMsg = 0x0299 = 665
  - plAvBrainGenericMsg = 0x038f = 911
- plNotifyMsg = 0x02ed = 749
- plLinkEffectsTriggerMsg = 0x0300 = 768
- plParticleTransferMsg = 0x0333 = 819
- plParticleKillMsg = 0x0334 = 820
- plAvatarInputStateMsg = 0x0347 = 839
- plInputIfaceMgrMsg = 0x0363 = 867
- pfKIMsg = 0x0364 = 868

Common data types

Assorted data types used by the message classes below.

Avatar brains

plArmatureBrain = 0x035b = 859
- plAvBrainHuman = 0x035c = 860
  - plAvBrainRideAnimatedPhysical = 0x049e = 1182 (unused, cannot be sent over the network)
- plAvBrainCritter = 0x035d = 861 (cannot be sent over the network)
- plAvBrainDrive = 0x035e = 862 (cannot be sent over the network)
- plAvBrainGeneric = 0x0360 = 864
  - plAvBrainCoop = 0x045f = 1119
- plAvBrainSwim = 0x042d = 1069 (cannot be sent over the network)
- plAvBrainClimb = 0x0453 = 1107 (cannot be sent over the network)

class plArmatureBrain : public plCreatable 

Class index = 0x035b = 859

Header: plCreatable class index header. (Strictly speaking, this isn’t part of the serialized plArmatureBrain itself, but in practice, plArmatureBrains are always serialized with a header.)
Reserved: 21 bytes. Set to 0 when writing and ignored when reading. For backwards compatibility with old Plasma versions.

class plAnimStage : public plCreatable 

Class index = 0x0371 = 881

Header: plCreatable class index header. (Strictly speaking, this isn’t part of the serialized plAnimStage itself, but in practice, plAnimStages are always serialized with a header.)
Animation name: SafeString.
Notify flags: 1-byte unsigned int. The following flags are defined:
- Enter = 1 << 0
- Loop = 1 << 1
- Advance = 1 << 2
- Regress = 1 << 3
Forward type: 4-byte unsigned int. The following types are defined:
- None = 0
- On key = 1
- Automatic = 2
Backward type: 4-byte unsigned int. Supports the same values as the forward type field.
Advance type: 4-byte unsigned int. The following types are defined:
- None = 0
- On move = 1
- Automatic = 2
- On any key = 3
Regress type: 4-byte unsigned int. Supports the same values as the advance type field.
Loop count: 4-byte signed int.
Do advance to: 1-byte boolean.
Advance to: 4-byte unsigned int.
Do regress to: 1-byte boolean.
Regress to: 4-byte unsigned int.

class plAvBrainGeneric : public plArmatureBrain 

Class index = 0x0360 = 864

Header: plArmatureBrain.
Stage count: 4-byte signed int. Element count for the following stage array.
Stages: Variable-length array. Each element has the following structure:
- Stage: Serialized plCreatable with header. Must be an instance of a plAnimStage subclass.
- Local time: 4-byte floating-point number.
- Length: 4-byte floating-point number.
- Current loop: 4-byte signed int.
- Attached: 1-byte boolean.
Current stage: 4-byte signed int.
Brain type: 4-byte unsigned int. The following types are defined:
- Generic = 0
- Ladder = 1
- Sit = 2
- Sit on ground = 3
- Emote = 4
- AFK = 5
Exit flags: 4-byte unsigned int. The following flags are defined:
- Any task = 1 << 0
- New brain = 1 << 1
- Any input = 1 << 2
Mode: 1-byte unsigned int. The following modes are defined:
- Entering = 1
- Normal = 2
- Fading in = 3
- Fading out = 4
- Exit = 5
- Abort = 6
Forward: 1-byte boolean.
Start message present: 1-byte boolean. Whether the following start message field is present.
Start message: Serialized plCreatable with header. Must be an instance of a plMessage subclass. Only present if the preceding boolean field is true, in which case the plCreatable should not be nullptr. If the preceding boolean field is false, this field is not present and defaults to nullptr.
End message present: 1-byte boolean. Whether the following end message field is present.
End message: Serialized plCreatable with header. Must be an instance of a plMessage subclass. Only present if the preceding boolean field is true, in which case the plCreatable should not be nullptr. If the preceding boolean field is false, this field is not present and defaults to nullptr.
Fade in: 4-byte floating-point number.
Fade out: 4-byte floating-point number.
Move mode: 1-byte unsigned int. The following modes are defined:
- Absolute = 0
- Relative = 1
- Normal = 2
- Standstill = 3
Body usage: 1-byte unsigned int. The following values are defined:
- Unknown = 0
- Upper = 1
- Full = 2
- Lower = 3
Recipient: plKey.

Avatar tasks

plAvTask = 0x036a = 874 (abstract)
- plAvAnimTask = 0x036b = 875
- plAvSeekTask = 0x036c = 876 (cannot be sent over the network)
- plAvOneShotTask = 0x036e = 878 (cannot be sent over the network)
  - plAvOneShotLinkTask = 0x0488 = 1160
- plAvTaskBrain = 0x0370 = 880
- plAvTaskSeek = 0x0390 = 912 (cannot be sent over the network)

class plAvTask : public plCreatable 

Class index = 0x036a = 874

Header: plCreatable class index header. (Strictly speaking, this isn’t part of the serialized plAvTask itself, but in practice, plAvTasks are always serialized with a header.)

class plAvAnimTask : public plAvTask 

Class index = 0x036b = 875

Header: plAvTask.
Animation name: SafeString.
Initial blend: 4-byte floating-point number.
Target blend: 4-byte floating-point number.
Fade speed: 4-byte floating-point number.
Time: 4-byte floating-point number.
Start: 1-byte boolean.
Loop: 1-byte boolean.
Attach: 1-byte boolean.

class plAvOneShotTask : public plAvTask 

Class index = 0x036e = 878

Identical structure to its superclass plAvTask (i. e. contains no data of its own). This message itself should never be sent over the network, but its subclass plAvOneShotLinkTask can be.

class plAvOneShotLinkTask : public plAvOneShotTask 

Class index = 0x0488 = 1160

Header: plAvOneShotTask.
Animation name: SafeString.
Marker name: SafeString.

class plAvTaskBrain : public plAvTask 

Class index = 0x0370 = 880

Header: plAvOneShotTask.
Brain: Serialized plCreatable with header. Must be an instance of a plArmatureBrain subclass.

`plMessage`

class plMessage : public plCreatable 

Class index = 0x0202 = 514

The serialized format has the following common header structure, with any subclass-specific data directly after the header.

Header: plCreatable class index header. (Strictly speaking, this isn’t part of the serialized plMessage itself, but in practice, plMessages are always serialized with a header.)
Sender: plKey. Identifies the object that sent this message. Might be nullptr?
Receiver count: 4-byte unsigned int (or signed in the original/OpenUru code for some reason). Element count for the following receiver array.
Receivers: Variable-length array of plKeys. Objects that this message should be sent to. May be ignored depending on the broadcast flags. Any of the elements might be nullptr?
Timestamp: 8-byte floating-point number. Allows artificially delaying the message so that it’s delivered only after a specific point in time has passed. If the time is already in the past, the message is delivered immediately. The value zero indicates that the message shouldn’t be delayed artificially.

Note

Although this field is serialized and sent over the network, it’s basically ignored in the serialized data. The timestamp is in local game time (as returned by hsTimer::GetSysSeconds), which only makes sense to the client that sent the message. When the message is sent over the network, the timestamp is converted to an absolute plUnifiedTime and stored in the delivery time field of the wrapper plNetMsgGameMessage. When the message is received, that absolute time is used to re-initialize this timestamp field with the corresponding local game time for the receiving client.
Broadcast flags: 4-byte unsigned int. Various boolean flags that describe how the message should be (and has already been) propagated locally and over the network. See plBCastFlags for details.

enum plBCastFlags

enumerator kBCastByType = 1 << 0

If set, the receiver objects array is ignored and the message is instead broadcast to all objects that have registered themselves as receivers for the message’s class or any of its superclasses.