Overall

Network communication in Terraria is done via a series of Messages. It is not a request/response system. The client sends messages when it wants to notify the server or changes (the player moves, for example), and the server sends messages when it wants to notify the client of changes (another player talks, for example).

That said, there are times when certain responses are to be expected. The login process, for example. This is laid out in the last section on this page.

The structure of the general message is defined below.

Type Formats

The types used in messages are little-endian.

Message Structure

Message Length is the length of Type + Payload in bytes. The smallest message is one without a payload, so Message Length would be 1 in that case.

The Payload is dependent on the Message Type, see below.

Message Types

What follows is a detailed list of all the available message types. It is also specified if the message is sent by the client or the server or both. The Message IDs are specified in hex, as indicated by the '$'. During the login process, the client is only allowed to send the messages marked with an asterisk. Attempts to send any other message will result in an error, and disconnection.

$01 — Connect Request (client → server) *

This is the first message sent by the client to the server when it connects. It also notifies the server of the client version.

Payload

$02 — Fatal Error (client ← server)

The server sends this whenever there is an error. It will drop the connection right after this is sent.

Payload

$03 — Connection Approved (client ← server)

The server sends this message when the connection is successful. It also sends the client's assigned player slot. All connected players are assigned a slot, 0-254.

Payload

$04 — Player Appearance (client ↔ server) *

This defines a player's appearance and name.

Payload

Client → Server

The client sends this as part of the login process to notify the server of the player's appearance. There is nothing preventing the client from sending this after the login process, however. The server will enforce the player slot, so any attempts to change the appearance of other players will just change your own.

Client ← Server

The server will send this to the client to notify the client of other players' appearance. The client should ignore this message if the player slot is its own, since the server is not allowed to change any of this data.

$05 — Set Inventory (client ↔ server) *

This specifies what item is in a specific inventory slot. Slots 0 to 58 are inventory slots, Slots 59 to 69 are armor/accessory slots. Slots 70 to 72 are dye slots. A stack of 0 means the slot is empty.

Payload

Client → Server

The client sends this to notify the server of the player's inventory. During the login process, the client sends 59 of these, one for each slot. It also sends this whenever the player modifies their inventory, either by moving something around, or pulling things out of chests, and so on. The server will enforce the player slot, so any attempts to modify the inventory of other players will just modify your own.

Client ← Server

The server sends this to notify the client of other players' inventories. The client should ignore this message if the player slot is its own, since the server is not allowed to modify your inventory.

$06 — Request World Information (client → server) *

Asks the server for world info. This is done as part of the login process.

Payload

None.

$07 — World Information (client ← server)

This message contains the basic information about the current world.

Payload

$08 — Request initial tile data (client → server) *

The client sends this message to the server to request initial tile data. The client specifies the player's spawn X,Y. This may or may not be the same as the server spawn. The server sends a lot of messages in response to this. See the Login process below for more detail.

Payload

$09 — Statusbar text (client ← server)

The server uses this message to show status text to the client. This text is shown in the upper right corner of the screen. Number of messages is the number of messages the client should show the status text for. If the client receives this message multiple times, the client should queue them up.

Payload

$0A — Tile Row Data (client ← server)

This contains a small row of tile data, starting at Tile X, Tile Y, and running for Width tiles.

Payload

The tile data is represented like so:

Byte	Flags: Bit Meaning 0 Tile Active 1 Not used 2 Has Wall 3 Has Liquid 4 Has Red Wire 5 Is Half Brick 6 Has Actuator 7 In Active
Byte	Flags: Bit Meaning 0 Has Green Wire 1 Has Blue Wire 2 Has Color 3 Has Wall Color 4-5 Slope
	If Has Color: Byte Color
	If Has Wall Color: Byte Wall Color
	If Active: Byte Tile Type   If Tile U,V is Important: Int16 Tile U Int16 Tile V
	If Tile has Wall: Byte Tile Wall
	If Tile has Liquid: Byte Liquid Amount Byte Liquid Type (0=water, 1=lava, 2=honey)
Int16	RLE Amount

RLE Amount is the number of times to repeat this tile horizontally, these duplicate tiles count towards the Width defined above.

$0B — Recalculate U/V (client ← server)

The client should recalculate any random U/Vs for this area. This includes the walls.

Payload

$0C — Spawn Player (client ↔ server) *

Sets player's spawn and respawn them.

Payload

Client → Server

The client sends this at the end of the login process to spawn the player. The server enforces the player slot so attempts to spawn another player will instead respawn the client's player.

Client ← Server

The server sends this whenever another player spawns.

$0D — Player Control (client ↔ server)

Set's the player's current position and velocity, along with their current control state.

Payload

Client → Server

The client sends this when the player presses a control. The server enforces the player slot so attempts to manipulate other players will just manipulate your own.

Client ← Server

The server sends this to notify the client of other players' movements. The client should ignore this message if the player slot is the client's, since the server is not allowed to modify any of this information.

$0E — Set Player Activity (client ← server)

Used to disable or enable players.

Payload

$0F — Unused

Unused message.

$10 — Set Player Life (client ↔ server) *

Used to set the player's health stats

Payload

Client → Server

The client sends this as part of the login process. The server enforces the player slot, so attempts to modify another person's health will only modify your own.

Client ← Server

The server sends this to notify the client of other player's health. The client should ignore this message if the player slot is the client's, since the server is not allowed to modify the player's health this way.

$11 — Modify Tile (client ↔ server)

Used to modify the world one tile at a time.

Payload

Client → Server

Sent by the client when the player modifies a tile.

Client ← Server

Sent by the server when someone else modifies a tile.

$12 — Set Time (client ← server)

Sets the current game time.

Payload

$13 — Open/Close Door (client ↔ server)

Open or Close a door

Payload

Client → Server

Sent when the player opens or closes a door.

Client ← Server

Sent when someone else opens or closes a door.

$14 — Tile Block (client ↔ server)

Updates a Length x Length block of tiles.

Payload

Tile Data is stored exactly the same as it is stored in Message $0A, except the RLE is not present. There are Length x Length tiles represented

Client → Server

I don't know why the client is allowed to send this. Especially since it doesn't go through anti-spam filters.

Client ← Server

Sent when the server needs to update a chunk of blocks, like with falling sand. The client should update the U/V of the received tiles.

$15 — Update Item (client ↔ server)

An item is modified in the world.

Payload

If Item ID is 0, this item slot is considered inactive.

Client → Server

Sent when a the player modifies an item in the world. If the item is to be created, Item Slot should be 200.

Client ← Server

Sent when an item in the world is modified. If the player created the item, the server won't tell the player about the item for a set amount of time, to prevent the player from accidentally picking it back up.

$16 — Set Owner of Item (client ↔ server)

Sets the owner of an item on the ground.

Payload

Client → Server

The client does this to disown an item. Setting the owner to 255. You can only do this for items you own. The server will force the new owner to be no one.

Client ← Server

The server sends this to notify the client of the owner of an item.

$17 — Update NPC (client ← server)

Sets info about an NPC. This could be either a friendly NPC or a Mob.

Payload

An NPC with Life of 0 means the NPC is not active.

AI is a series of floats that somehow determine how the NPC moves

$18 — Strike NPC (client ↔ server)

Hit an NPC with your currently equiped item

Payload

Client → Server

The client does this when the player hits an NPC. The server will enforce the Player slot, so you cannot force another player to hit something.

Client ← Server

The server sends this when another player hits an NPC. This may even be your own player, the server is able to force that.

$19 — Chat (client ↔ server)

Text chat

Payload

Client → Server

The client sends this when the player says something. The client doesn't parse any special commands.

Client ← Server

The server sends this when another player (or the server) says something. The server will not prefix the player's name in the text, it's up to the client to do that. A player slot of 255 means the client should not prefix the player's name since it is either a server message, or a player action.

$1A — Damage Player or PvP (client ↔ server)

Player takes damage, or attacks another player

Payload

Client → Server

Client sends this to attack another player. The server will ignore this message unless both players have PvP enabled.

Client ← Server

The server will send this if you or another player takes damage for any reason.

$1B — Update Projectile (client ↔ server)

Create or modify a projectile

Payload

Projectiles have Identities rather than slots because they are so numerous. Projectiles instead are identified by their identity (random id), and owner slot

Client → Server

Client sends this when a player creates or somehow modifies a projectile.

Client ← Server

The server sends this whenever another player creates or modifies a projectile.

$1C — Damage NPC (client ↔ server)

NPC is damaged, by projectile or other means. Passing a negative damage value will insta-kill the NPC.

Payload

Client → Server

The client sends this when an NPC is hit by a projectile or harmed by other means

Client ← Server

The server sends this when it determines the NPC is harmed

$1D — Destroy Projectile (client ↔ server)

Remove projectile

Payload

Client → Server

The client sends this when a projectile is destroyed. The server enforces the player slot, so you may not delete other players' projectiles

Client ← Server

The server sends this when a projectile is destroyed by another player.

$1E — Toggle PvP (client ↔ server)

Turns PvP on or off

Payload

Client → Server

The client sends this when the player toggles PvP. The server enforces the player slot, so attempts to toggle someone elses' PvP will simply toggle your own.

Client ← Server

This is sent by the server, along with a chat message, whenever someone else toggles PvP.

$1F — Request Open Chest (client → server)

Requests the contents of a chest.

Payload

$20 — Set Chest Item (client ↔ server)

Identifies an item in a chest

Payload

Client → Server

The client sends this whenever the player modifies the contents of a chest. Either by adding or removing something, or just moving items around.

Client ← Server

The server sends this when you request the contents of the chest. It does not broadcast other players' modifications of chests.

$21 — Open/Close chest (client ↔ server)

Flags a chest as open or closed.

Payload

Client → Server

The client calls this with chest slot -1 to signify that they've closed the chest.

Client ← Server

The server sends this when it's finished sending the contents of a chest, to indicate that the chest is now opened by you. It may also send -1 if the chest is forced closed for any reason.

$22 — Destroy chest (client → server)

Breaks a chest, or does nothing if the chest is full

Payload

$23 — Heal Player (client ↔ server)

Heals a player

Payload

Client → Server

Sent when the player uses a potion or heals himself somehow. The server enforces the player slot, so you cannot heal someone else.

Client ← Server

Sent by the server when another player heals himself, or if something out of the player's control heals the player.

$24 — Set Zones (client ↔ server)

Sets the player's zones

Payload

Client → Server

Sent by the client to let the server know what zones are currently active based on the types of tiles in the area.

Client ← Server

Sent by the server to notify the client about the zones of other players.

$25 — Request Password (client ← server)

Server requires a password to join. After the server sends this, it will accept no other packets except for $26.

Payload

None

$26 — Login with Password (client → server) *

Sends the server password.

Payload

$27 — Unassign item (client ← server)

Unassigns an item on the ground. This works just like $16, except the new owner is always nobody (255).

Payload

$28 — Talk to NPC (client ↔ server)

Talks to an NPC

Payload

Client → Server

The client sends this when the player talks to a friendly NPC. The server enforces the player slot, so you cannot force other players to talk to NPCs.

Client ← Server

The server sends this to notify you that other players (or yourself) are talking to an NPC.

$29 — Animate player flail (client ↔ server)

Animates an item carried by a player

Payload

Client → Server

The client sends this to animate flails. The server enforces the player slot, so you may not animate other players' flails.

Client ← Server

The server sends this to notify the client of other player's animations.

$2A — Set Player Mana (client ↔ server) *

Sets player's mana and max mana

Payload

Client → Server

Client sends this as part of the login to specify the mana levels. The server enforces the player slot, so you may not set mana for another player.

Client ← Server

The server sends this to notify you of other player's mana levels, or to adjust your own.

$2B — Replenish Mana (client ↔ server)

Rejuvenates player mana

Payload

Client → Server

Client sends this when the player takes a mana potion or some other mana regeneration. The server enforces the player slot so you can't rejuvenate another player's mana.

Client ← Server

Server sends this to notify you of other player's mana regeneration, or to affect your own.

$2C — Kill Player (client ↔ server)

Kills a player

Payload

Client → Server

Client sends this if the player dies. The server enforces the player slot so you cannot kill another player.

Client ← Server

The server sends this to notify the client of another players' death. The client should ignore this message if the player slot is the clients.

$2D — Change Party (client ↔ server)

Changes the player's party

Payload

Client → Server

Client sends this when the player changes parties. The server enforces the player slot so you cannot affect the parties of other players.

Client ← Server

Server sends this when another player changes parties, or if your party is changed somehow.

$2E — Read Sign (client → server)

Requests to read a sign

Payload

$2F — Set Sign Text (client ↔ server)

Changes a sign's text.

Payload

Client → Server

The client sends this when the player changes the text on a sign.

Client ← Server

The server sends this when the player requests to read a sign.

$30 — Adjust Liquid (client ↔ server)

Adjust the liquid at a tile

Payload

Client → Server

Client sends this when a player dumps liquid on the ground.

Client ← Server

Server sends this to notify the client of flowing liquid.

$31 — Spawn (client ← server)

Initialization complete, request to spawn.

Payload

None.

$32 — Set Player Buffs (client ↔ server) *

Set's the player's active buffs

Payload

Client → Server

Client sends this during initialization, or when the player activates multiple buffs. The server enforces the player slot, so you cannot change the buffs of another player.

Client ← Server

Server sends this to notify you of other players' buffs. You should ignore this if the player slot is the clients', since the server is not allowed to modify your buffs.

$33 — Old Man's Answer (client ↔ server)

Answer's the old man's question to free him of the curse

Payload

Client → Server

Client sends this as a response to the old man's question, either to take on skeletron, or not.

Client ← Server

The server sends this if another player declined to break the curse.

$34 — Unlock Chest or Door (client ↔ server)

Unlocks a chest or door

Payload

Client → Server

The client sends this to unlock a locked chest or door.

Client ← Server

The server sends this to notify the client that someone else unlocked a chest or door.

$35 — Add an NPC Buff (client ↔ server)

Adds a buff to an NPC

Payload

Client → Server

Client sends this to notify the server that an NPC was buffed.

Client ← Server

Server sends this whenever an NPC was buffed.

$36 — Set NPC Buffs (client ← server)

Sets all of an NPC's buffs

Payload

The structure of each Buff is:

$37 — Add Player Buff (client ↔ server)

Adds a buff to a player

Payload

Client → Server

The client sends this when the player adds a single buff.

Client ← Server

The server sends this when your player was buffed. The client should ignore this if the player slot isn't the client's.

$38 — Set NPC Name (client ← server)

Sets the name of an NPC

Payload

$39 — Sets Balance Stats (client ← server)

Sets the amount of hallowed vs corruption

Payload

$3A — Play Harp (client ↔ server)

Plays a harp

Payload

Client → Server

Sent when the player plays a harp. The server enforces the player slot, so you cannot force another player to play a harp.

Client ← Server

Sent when another player plays a harp.

$3B — Flip Switch (client ↔ server)

Flips a switch

Payload

Client → Server

Sent when the player flips a switch.

Client ← Server

Sent when another player flips a switch.

$3C — Move NPC Home (client ↔ server)

Moves an NPC home

Payload

Client → Server

Sent when the player moves an NPC's home, or makes an NPC homeless using the housing menu.

Client ← Server

Sent when another player moves an NPC's home, or an NPC moves in on its own.

$3D — Summon Boss or Invasion (client → server)

Summons a boss or invasion at player position

Payload

$3E — Ninja/Shadow Dodge (client ↔ server)

Perform a Ninja or Shadow Dodge

Payload

Client → Server

Sent when client performs the dodge

Client ← Server

Sent to announce to other players that the player dodged

$3F — Paint Tile (client ↔ server)

Paints a tile

Payload

Client → Server

Sent when client paints a tile

Client ← Server

Sent to announce to other players of a paint change

$40 — Paint Wall (client ↔ server)

Paints a wall

Payload

Client → Server

Sent when client paints a wall

Client ← Server

Sent to announce to other players of a paint change

$41 — Teleport Player/NPC (client ↔ server)

Teleports a player or NPC with an animation

Payload

Client → Server

Sent when player teleports

Client ← Server

Sent when NPC or other player teleports

$42 — Heal Player (client ↔ server)

Quick heal player

Payload

Client → Server

Sent when client heals himself

Client ← Server

Sent when other player heals

$44 — Unknown (client → server)

Unknown

Payload

Message Flow

Certain messages expect certain responses, some messages take on different meanings when coming from the server or the client. I figured I'd cover the basics here.

Allowed messages

The client is only allowed to send messages marked with an asterisk until it goes through the login process and the server bumps your state up to Playing (10).

General server responses

When the client does something like notify the server of the player appearance (by sending $04), the server will take note of that information, and then echo that same information back to all connected clients... including the person who sent the information in the first place. This means for many messages, you might get an echo back.

Client logging into Server

When a client connects to a server, it sends $01 as the first message. The server will then respond with either $03 if your connection was approved or $25 if the server requires a password. The server may also respond with $02 if your IP was banned.

If a password is required, the client should then send the password with $26. The server will then respond as before; $03 if approved, $02 if there was a problem. Once you're approved, the server classifies your connection as Initializing (1).

Once the client receives $03, it should send $04 to notify the server of the player's appearance. Then, without waiting for a response, it should send $10 to set the player life, $2a to set the player's mana, and $32 to set the player's buffs. Next, the client should loop through the player's inventory slots (0 to 72) and send $05 for each one. Finally the client should send $06 to request world information.

If the server has a problem with your name set in $04, it will kick you with an error ($02).. otherwise the server will be echoing out your information to all other clients. Finally, the server will respond to your request for world information with $07. It will then bump your state up to Initialized (2).

Once the client receives $07, it should send request the initial tile data for the spawn with $08, giving it the spawn X and spawn Y it received with the world information.

The server will respond to $08 by sending a status update $09, followed by several $0A around the spawn. It will send $0B telling you to recalculate the areas that need recalculating. Then it will send $15 and $16 for items on the ground. It will also send $17 for all NPCs in the world. Then it will send $31 telling the client to spawn, $39 giving the balance stats for the world, and finally $38 for all Named NPCs.

When the client receives $31, it should then send $0C to spawn the character in the world. At this point the server kicks your state up to Playing (10). After this, any messages can be sent between the client and server.