client-message

A client message is one module under lib/game/inbound/ (ThistleTea.Game.Inbound.CmsgFoo) that both decodes its payload and handles the decoded struct by calling into the world.

The inbound layer sits above the world: it may call World, Core, Network, and Auth, but nothing below it may reference an inbound module. boundary rejects that at compile time. World code never names a client message; the player process applies one through the ThistleTea.Game.World.ClientInput protocol, which the use macro implements.

Module

Create or modify a module under lib/game/inbound/ that:

• has use ThistleTea.Game.Inbound.ClientMessage, :CMSG_FOO
• defines a defstruct matching the fields decoded from the payload
• implements from_binary/1 using little-endian bit syntax patterns like <<x::little-size(32)>>
• implements handle/2, which pattern matches %__MODULE__{} and dispatches into a world system

Then register the opcode in @messages in lib/game/inbound/dispatch.ex so packets decode into the struct.

The macro aliases ClientMessage, Message (server messages, ThistleTea.Game.Network.Message), BinaryUtils, and MovementBlock. Alias the world modules the handler calls yourself.

Use use ThistleTea.Game.Inbound.ClientMessage, opcode: :CMSG_FOO, while_possessed: true only for messages a player's client must still be able to send while another unit possesses the player. These are connection, chat, logout, cache query, and movement acknowledgement traffic. Everything else is suspended during possession.

A minimal payload, CMSG_GROUP_INVITE:

defmodule ThistleTea.Game.Inbound.CmsgGroupInvite do
  @moduledoc false
  use ThistleTea.Game.Inbound.ClientMessage, :CMSG_GROUP_INVITE

  alias ThistleTea.Game.World.Entity.Player.Groups

  defstruct [:name]

  @impl ClientMessage
  def from_binary(payload) do
    {:ok, name, _rest} = BinaryUtils.parse_string(payload)
    %__MODULE__{name: name}
  end

  @impl ClientMessage
  def handle(%__MODULE__{name: name}, state), do: Groups.invite(state, name)
end

A payload with strings, from CMSG_MESSAGECHAT:

def from_binary(payload) do
  <<chat_type::little-size(32), language::little-size(32), rest::binary>> = payload
  {:ok, message, _rest} = BinaryUtils.parse_string(rest)

  %__MODULE__{
    chat_type: chat_type,
    language: language,
    message: message
  }
end

Handling

• Keep handle/2 as dispatch: destructure the message and call a system module (World.Entity.Player.*, World.System.*). Game logic belongs in that system module or in Core, not in the message module.
• state is the player process state once the character is in the world. Messages that arrive before login (auth, character screen, ping) get the connection's %ConnectionState{}. Inbound.Session handles pings on the connection even after login.
• Every clause matches %__MODULE__{} in its head. Guard on state (%{ready: true}, in-combat checks) with extra clauses, and end with a def handle(%__MODULE__{}, state), do: state fallback when some states should ignore the message.
• World code never names an inbound module. Destructure a few fields in the head and pass them, or hand the whole struct to a world function that reads many of its fields (Mail.send_mail/2, Auction.search/2).
• MSG_MOVE_* is the exception: Network.Message.MsgMove stays in Network because the world also builds and rebroadcasts it. Its ClientInput implementation lives in lib/game/inbound/msg_move.ex.

How to find the packet spec

• refs/vmangos/ is the primary reference for 1.12 behavior and packet layouts; refs/mangos/ is secondary.
• Packet formats are also cataloged in refs/wow_messages/wow_message_parser/wowm/*/${CMSG_NAME}.wowm, but those specs are sometimes wrong, so cross-check against vmangos.
• Thistle Tea is a Vanilla (patch 1.12.1) server, so ignore future client versions.