About this book

A wire protocol specification for League of Legends game servers: what a server sends for a client to connect, load a match and play, and what the client does with it. The chapters are meant to be enough to build a conforming server. Each builds on the ones before it, so read them in order.

A chapter holds for every client build covered, except a passage set apart and headed with ranges, which holds for those alone. What a chapter says of a message holds wherever that message has a layout: a build with no layout for a message has no such message, and nothing said of it applies there. Field layouts are not restated in prose: they live in schema/, machine readable, and each system’s chapter ends with its messages and every layout each has. Where a field’s meaning is undetermined, its note says so.

The rules of the game are out of scope: how much a spell deals, what an item costs, how fast a champion levels. A server decides those; the specification says how it tells a client the results.

Check your work against conformance/ as you go; its vectors are this specification’s measure of a conforming server.

If the specification does not answer something you need, do not guess: report it as a defect, as CONTRIBUTING.md explains.

This book covers client builds from 4.1.0.171 up to, not including, 4.21.0.0, in 19 ranges. Every build in a range is held to the same facts.

What the chapters say of a message says nothing of a patch that has no layout for it. A message the chapters name with a link is one this book has; one named without a link is one no build of this book has. The index of messages finds any message, and the appendix on patches gives each patch’s checks, every message it carries, and how it differs from the one before it.

Transport

A server and a client exchange messages over UDP, carried by ENet 1.2.5 with the header each range’s definitions give.

Layering

Four layers carry a message to a socket.

1. UDP moves datagrams.
2. ENet turns datagrams into ordered, acknowledged deliveries on numbered channels.
3. A cipher covers each channel payload.
4. A message occupies the deciphered payload, opening with the header its family carries, as Messages defines.

This chapter covers layers 1 to 3.

Stock ENet

This document does not restate ENet. Connection setup, acknowledgement, sequence numbers, retransmission, throttling, and fragmentation behave as ENet 1.2.5 defines them.

The rest of this chapter says what a client does not accept from stock ENet. A server built on an unmodified ENet 1.2.5 never completes a connection.

The packet header

Each range has its own header, below with the constants it is read under. A server MUST use the layout of the version it serves, because a client establishes no connection under any other layout.

Packet headers and constants

In 4.1–4.19

ENet 1.2.5 beneath; little-endian fields. Blowfish in ECB mode over 8-byte blocks, each read big-endian, under a 16-byte key given in base64. Neither end pads.

In 4.20

ENet 1.2.5 beneath; little-endian fields. Blowfish in ECB mode over 8-byte blocks, each read big-endian, under a 16-byte key given in base64. Neither end pads.

A header built from the schema is necessary to reach a client, and not sufficient on its own. Where a field’s content is free rather than fixed, its note in the schema says so.

conformance/vectors/transport holds a header with a sent time and one without.

A client discards any datagram shorter than the minimumDatagram constant of its range. A server MUST NOT send a shorter datagram.

The connect command

A server’s verify connect MUST state the channel count, and the throttle interval, acceleration and deceleration, the connect command carried: a client abandons a connection whose verify connect states anything else.

A client’s connect command takes ENet’s layout, except that two of its fields carry one byte of meaning each. The peer id is the first of the two bytes ENet gives it, and the session id is the first of the four. The bytes after each carry nothing a server reads, and a client fills them with anything.

A server MUST take the peer id and the session id from those first bytes. The session id is then the byte every header carries, and a server that reads either field at ENet’s width answers a client that never hears it.

A client asks for 8 channels.

Maximum transmission unit

A client asks for a transmission unit of 1400 bytes, and discards any datagram whose UDP payload, packet header included, exceeds the maximumTransmissionUnit constant of its range. A server MUST NOT send a larger datagram.

That constant is below what a client asks for. A server MUST accept a connection at a transmission unit no greater than the constant, by clamping the value the client asks for. Capping its own sending without clamping the negotiated value is not sufficient, because ENet derives fragment sizes from the negotiated value and still emits datagrams above the limit.

The cipher

Whether a payload is enciphered follows from the state of the connection rather than from the channel it travels on. A connection begins with no cipher state, and the request that establishes it travels in the clear apart from one field it carries enciphered as proof. Everything after that is enciphered, on every channel and in both directions, the answer to that request included.

schema/protocol.json records which cipher, in which mode, and the shape of a block. A server MUST use that cipher; a client accepts no other. A standard implementation of Blowfish interoperates with a client.

What a server sends carries no padding. Trailing bytes that do not fill a block travel unchanged, so a payload shorter than one block travels in the clear.

What a client sends carries no padding either.

conformance/vectors/cipher covers a whole block, a payload with a tail too short to fill one, and a payload shorter than a block.

The key

Both ends hold the key before a connection opens. Nothing on the wire negotiates it, and no exchange derives it. A client receives it as a launch argument.

The argument holds the key in base64.

Registration associates the key with a connection. Register travels in the clear apart from one field enciphered under the key, and a server MUST refuse a connection whose deciphered field is not what it expects, since that field is all that shows the client holds the key. schema/messages records the exchange, as Register and Registered.

Channels

In every range of this book

Messages

A message occupies one deciphered channel payload. The payload opens with the header the message’s family carries, and the body begins where that header ends.

schema/messages holds one file per message identity, and each file records one or more revisions. A revision carries the value identifying the message, the channel it travels on, its direction, how the transport delivers it, and the fields of its body.

Families

Every channel carries one family of messages, and schema/channels.json says which. A family fixes two things: the numbering its command values are drawn from, and the header that precedes every body on it. schema/families.json records both. Two channels of one family share a numbering, so a value identifies at most one message across both, and the same value on channels of different families is two unrelated messages.

A family whose header carries no command field has one message each way on each channel it rides, read from the payload’s first byte; its revisions number that message 0.

The family, not the channel, selects the header.

A revision names the channel it travels on, and names any others in alsoOn. Those channels carry the same family, so the command value means the same message on each, and the body is byte for byte the one the revision records. What changes between them is delivery: each entry states how the transport carries the message there. A server MAY send such a message on any channel the revision names, and what it gets is the delivery stated for that channel. A client reads it the same way on every one of them, so a server MUST NOT vary the body with the channel it chooses.

The command

A revision records the value that identifies it, and the family’s header says where that value sits on the wire. That value is not a field of the message: it belongs to the header, along with anything else the family carries before a body begins.

A family can keep some values of the leading byte for framing rather than for messages, and schema/families.json lists which. Where a family names an escape, that value means the real identifier is wider than a byte and travels elsewhere in the header, which is how a family numbers more messages than a byte holds. A revision records the identifier either way, and never the escape.

Directions

A revision states whether it travels clientToServer, serverToClient, or bidirectional. Direction is part of what identifies a message, so one value serves two messages travelling opposite ways within a family. A bidirectional revision claims that value both ways.

A container of several messages

Where the game family keeps 255 for framing, that value introduces a container rather than a message: a run of several messages gathered into one payload, which a reading end unwraps and reads one by one as though each had arrived on its own. A container carries no header, so nothing in schema/messages describes one, and a reading end MUST NOT read the value that introduces it as a command.

A container is the byte 255, then a count of entries in one byte, then the entries one after another. The first entry is a length in one byte, the command in one byte, the object identifier in four bytes, and then a body whose size is the length less five. Every later entry opens with a byte of flags and size:

• bit 0 clear: a command byte follows, and this entry carries it; bit 0 set: this entry carries the command the entry before it carried;
• bit 1 clear: a four byte object identifier follows; bit 1 set: one signed byte follows, and this entry’s object identifier is the one before it plus that byte;
• bits 2 to 7: the size of the body; where they read 63, the size is the next byte instead.

The body follows. Each entry, given the command and object identifier it carries as its header, is a message read as though it had arrived on its own. Where the family’s escape is 254, an entry whose command is 254 carries the wider identifier in the first two bytes of its body, so that, with the command and object identifier before it, it reads as the extended form of the header does.

Where the game family keeps 255, a server MAY send a container on the events channel. A client sends none.

Reading a body

A body begins where its family’s header ends. Fields occupy it in the order the revision lists them, each beginning where the one before it ended. A revision never restates a field its family’s header already carries, and never takes a name from it. Nothing is aligned and nothing is padded between fields. A field’s size is fixed by its type, given as a literal, carried by an earlier field, or one of the two words below.

Where a size or a count names an earlier field, it names one that has already been read and one holding an unsigned integer. It names either a whole field or one run of bits inside a field, and a run is written as the field name, a full stop, and the run name. remaining and terminated are reserved words rather than names, so no field carries either.

A field of a body names only fields of that body. A family’s header is read first, but it belongs to every message of the family rather than to this one, so nothing in a body is sized or governed by it.

What counts as an earlier field depends on what encloses the field doing the naming. An item of an array reaches the fields of the body around it. The fields of a struct reach only each other, because a struct is used wherever it occurs, so it cannot depend on what surrounds any one use.

remaining means every byte from where the field begins to the end of what encloses it: the message body, or the byte length of the struct or array the field sits inside. A field measured that way is the last one its enclosure defines, because nothing inside that enclosure can follow it.

An enclosure that states a byte length is itself an ordinary field, and fields follow it as usual. An enclosure that states none ends where the body ends, so it is the last field too, and so is any struct whose own last field is one of these.

A body ends where its last field ends, with one exception: a client accepts a Registered carrying bytes past its record, and takes no meaning from them. A sender MUST write the fields a revision lists and nothing after them.

Byte order

A revision of schema/protocol.json states the byte order that covers a version range, and every multi byte field in that range is read that way. A field that differs states its own order, which overrides the range.

The types

Integers. u8 through u64 and i8 through i64, in two’s complement. f32 and f64 are IEEE 754 binary floating point.

Bytes. A run of bytes with no interpretation. Its size is fixed, named by an earlier field, or remaining.

Strings. A run of bytes and an encoding, either utf8 or ascii. A size is a literal or the name of an earlier field. A string given one occupies that many bytes whatever its content, and the zero bytes at its end are padding rather than content, so they are dropped. A zero anywhere else belongs to the text and stays. A string sized terminated ends at the first zero byte, that byte belongs to the field, and it is the only one dropped. A string sized remaining carries every byte to the end of its enclosure, zeros included. A size counts bytes rather than characters.

Arrays. A run of one repeated shape. An array states either a count of items or a size in bytes, and never both. A count is a literal, the name of an earlier field, or remaining, which repeats to the end of the enclosure. A size in bytes repeats until those bytes are consumed, which is how a run whose length travels as a byte count is recorded.

Structs. A named group of fields, defined in schema/types and used wherever it occurs. A struct has revisions as a message does, and a message revision that holds one lies wholly within one of the struct’s revisions, which gives the layout it holds there. A struct occupies exactly the bytes its own fields occupy. Where its length travels on the wire instead, the field states a size in bytes, as a literal or as the name of an earlier field. A sending end MUST write a struct’s fields to fill that size exactly.

Bits. A field of one or more bytes divided into named runs, whose widths total exactly the bits those bytes hold. No run is wider than 32 bits. The bytes form one little endian word whatever the range’s byte order, or a big endian one where the field says so. Runs are listed from the least significant bit upward, and each reads as an unsigned integer of its own width.

Bit arrays. A run of the same group of bit runs, repeated a stated number of times. The groups follow one another from the low bits of the first byte upward, crossing byte boundaries without padding, and the field occupies as many whole bytes as the groups need. The bits above the last group are clear. A count is written as an array’s is.

Records. A group of fields named together and read one after another, with nothing between them and nothing around them. A record occupies exactly what its fields occupy. Unlike a struct it is written where it is used rather than defined in schema/types, and its fields reach the fields around it, so a record is a way of naming part of a message rather than a shape reused elsewhere.

What a field names

A size, a count, or a rule about whether a field is present names an earlier field. Five forms are written:

• a name on its own, which is a field of the same enclosure;
• a name, a full stop, and a run inside it, where that field is bits;
• a name, square brackets, and a name inside them, which is the item of an earlier array standing at the same position as the item doing the naming, so that two arrays run together;
• either of the first two inside {"field": …, "minus": N}, which is that field’s value less the literal N, and N is never larger than the value;
• either of the first two inside {"field": …, "bitsSet": true}, which is how many bits of that field’s value are one.

Nothing else is computed.

Presence

A field states a presence rule when it occupies bytes only under a condition, and a field whose condition does not hold occupies no bytes at all. The rule names an earlier field or bit run holding an integer, and states a value it carries, or a set of values, any one of which satisfies it. Without one, any value other than zero satisfies the rule. A field its own rule left out holds no value, so a rule naming that field does not hold either.

A rule can instead name remaining, which no field is called. A field under that rule is present where the payload has bytes left at that point and absent where it has ended, so a message whose sender stops early reads as one whose later fields are absent. A sender that stops early MUST stop where a field under such a rule begins.

A rule can mark one of its sides unseen; that side’s layout is the one the field states.

A field that travels enciphered

A payload is enciphered as a whole once a connection has a cipher state, and a message says nothing about that. Before a cipher state exists, a payload can carry one field enciphered under the key both ends hold, and the field says so.

Such a field occupies whole cipher blocks, because a field filling part of one would travel half in the clear. Its recorded value is what the bytes mean once deciphered, so a reader deciphers the field alone and leaves the payload around it untouched.

Enumerated values

Where an integer field, or a run of bits inside one, takes a fixed set of values, the field lists what they mean, keyed by the value on the wire. Each entry names the value, in the same form a field name takes, and no two entries of one field share a name. A key fits the width and sign of what it names. A value with no entry has no meaning this specification states.

Revisions

A revision covers a range of client versions, from one version inclusive to another exclusive. Every revision states where it stops. Ranges of one message never overlap. A version no revision of a message covers has no such message: a client there neither sends nor takes it, and what a chapter says of it does not apply.

A revision covers no version that schema/protocol.json, schema/channels.json and schema/families.json do not all describe, because a range none of them reaches has no header, no byte order, and no channel to travel on.

Names and notes

A field name begins with a lower case letter and carries letters and digits after it. A message identity and a struct identity begin with a capital. A file is named for the identity it defines, and a message’s vectors sit in one directory named for that identity, with each capital starting a new part, lower case and joined by hyphens.

A field name is unique among the fields beside it, and an item of an array never takes the name of a field enclosing it.

Anything in schema/ carries a note wherever a fact needs words: a revision, a field, a run of bits, a value. A note states what the wire carries and what each end does. It carries no requirement keyword and says nothing changed.

How a message is delivered

A revision states whether the transport carries it reliably, unreliably, or unsequenced, which is what the message needs of the transport: a message another supersedes can be lost, and one that carries an account of what happened cannot. A server MUST send a message with the delivery its revision states.

Quick chat

Quick chat is a feature a server leaves off. A client sends a quick chat on channel 6 only where VersionSync’s features turn quick chat on. This specification records no layout for channel 6.

Vectors

Every revision carries at least one conformance vector. A message vector opens with its family’s header and is read to the end. conformance/ says how a vector is written and how to run one.

Family headers

A field present when remaining is set is present exactly where the payload has bytes left at that point.

In every range of this book

The game family:

The session family:

The registration family:

Objects and identifiers

How the things a match is about are named on the wire, and when an object enters and leaves a client’s world.

The identifiers

A field’s own definition gives its exact type. Where a field carries one of these, it carries it whole, at the width above.

No region id stands for no region.

A server MUST give each player a client id from 0 to 252.

How they relate

A player is known by a player id. A server answers a client’s Register with Registered, and the one carrying the client’s own player id gives the client its own client id.

Registration pairs each player id with a client id: a server answers a client’s Register with one Registered for every seat. Every later message that names a player by client id is read through that pairing.

Roster lists each side’s player ids in order, and a player’s seat is their place in that list. A client finds a seat’s client id through its player id. SeatName, SeatChampion and the VersionSync seats name a player by player id; SeatLoadProgress names both.

A champion carries the client id of the player it belongs to. The CreateChampion carrying a client’s own client id makes that champion the client’s own.

A bot’s champion carries 4294967295.

Net ids

A net id names one object in a client’s world: a unit, a missile, a particle, a marker, a prop. The header of every game message carries one, and fields naming a unit, an owner or a target carry one too.

• A server MUST NOT give an object net id 0, which names nothing.
• A server SHOULD NOT give an object a net id whose top byte is 0xFF, which the identifiers of what a map holds use, nor one whose top byte is any client’s client id plus 1, which a client uses for objects of its own making.
• A server MUST NOT give a new object a net id it has given another object in the same match, except in a soft reconnect (see below).

A client that still holds the earlier object creates the new one but keeps the net id on the old one, so messages naming it reach the old object, and removing either leaves the id naming neither.

A create message carries a node beside the object’s net id.

Nothing a player sees depends on it.

Net ids of what a map holds

Some objects are on the field before any message puts them there, and no message ever does: the buildings a side defends, the shops beside them, and the spawn points a side’s minions come from. A receiving end knows them from the map it loaded, and every message naming one names it by an identifier worked out from that object’s name in the map.

The identifier is the CRC-32 of the name, with the top byte set:

identifier = crc32(name) | 0xFF000000

The name is taken byte for byte with its case kept, so OrderShop01 and orderShop01 are two names and give two identifiers. The CRC-32 is the common one: the polynomial 0x04C11DB7 read reflected, starting from 0xFFFFFFFF and finishing with every bit inverted, so the nine bytes 123456789 give 0xCBF43926.

Among the identifiers with that top byte are these:

The Barracks names above belong to inhibitors, whatever the name says. The minions a side sends out come from spawn points of their own, which are among the objects a map holds.

A client puts a minion on the field for a SpawnFromBarracks naming a spawn point, and creates nothing for one naming an inhibitor such as Barracks_T1_C1.

A server MUST name each object a map holds by the identifier its name gives.

CreateTurret gives a net id to a turret the map already holds, matched by name. Given to a turret that already has one, it gives it a second, and both name it.

What a client holds

A client holds an object from the message that creates it until the message, or the end of its life, that removes it. Creating messages are listed in Units. What a map holds, a client holds from the moment it loads the map.

Several creating messages can arrive inside the EnterSight that brings a unit into view.

Leaving a client’s sight removes nothing: LeaveSight and LeaveTeamSight hide an object, and it is held as before.

LeaveLocalSight hides an object too, and it is held as before.

A soft reconnect

SoftReconnect rebuilds a client’s world without a new connection, in two halves. The first marks every unit and every object kept until a checkpoint, inhibitors aside. A create message for a marked net id replaces the marked object rather than keeping the id on it. The second removes every object still marked. In between, a server sends again each object the client is to keep. Each stage either marks or removes.

Messages about objects a client does not hold

A message whose header names a net id the client does not hold, or whose body names one it needs, does nothing, and the client answers nothing for it. Creating messages are the exception, and so are these:

• CreateFollower does nothing where the unit it follows is not held.
• A Replication batch skips the units a client does not hold, and goes unanswered (see Ordering).
• SoundPlayed naming an owner the client does not hold plays the sound with no place.

SpawnPet takes the net id in its header for the new pet, but does nothing where the owner its body names is not held.

A WaypointGroup or WaypointGroupAtSpeed path for a unit not yet held is applied once an object takes that net id, and its WaypointAck is sent as usual. A server SHOULD send the creating message first.

EnterSight and EnterLocalSight act on the messages they carry whether or not the client holds the unit they name.

Nothing else is held back for later: a message that arrives before the message creating what it names is lost. Ordering says what that requires of a server.

A message naming its sender

A server MUST set any field naming the sender from the connection the message arrived on, and MUST NOT copy the value the message carried; otherwise one player can send messages every other client attributes to another.

Name hashes

Some things a message names are known to a client by name: a spell, an effect a unit carries, a particle, and a place on a unit that particles hang from. A message names one of these by a number worked out from its name.

The number is the ELF hash of the name with its capital letters lowered:

number = 0
for each byte b of the name, with A to Z made a to z:
    number = (number << 4) + b
    high = number & 0xF0000000
    if high != 0:
        number = number ^ (high >> 24)
    number = number & ~high

Every step is worked in 32 bits. Only A to Z change, so SummonerFlash and summonerflash give one number. A particle’s name includes its extension, so the number comes from global_ss_flash.troy and not from global_ss_flash. The nine bytes 123456789 give 0x0678AEE9.

Every byte other than A to Z is taken as it is.

A server MUST name each such thing by the number its name gives.

Ordering and acknowledgement

What arrives in what order, which numbers say that one statement supersedes another, and what a client answers with. A server whose messages arrive out of the order these rules expect has them ignored or lost.

Across channels

The transport delivers a channel’s reliable messages in the order they were sent, and drops an unreliable message that arrives after a later one on the same channel (see Transport). Nothing orders one channel against another.

A client acts on game messages in the order they arrive, whichever channel they arrive on, and holds none back for later but the paths Objects and identifiers names. A message that arrives before the message creating what it names is lost. So:

• A server MUST send the message creating an object before any message naming it.
• A server MUST NOT rely on a message on one channel arriving before a message sent later on another. Where one depends on the other, a server sends both on one reliable channel, or sends the second once the transport has acknowledged the first.

The messages creating a unit travel reliably on the events channel, while Replication and WaypointGroup travel unreliably on the transient channel, so either can overtake the message creating the unit it names. A Replication batch skips a unit the client does not hold, and goes unanswered (see below), so a server sends a newly created unit’s values again until a batch naming it is answered.

A server can instead send Replication reliably on the events channel.

Numbers that supersede

Several messages carry a syncId: a number that lets a client tell a newer statement from an older one, or a server tell which statement an answer is for. Each family keeps its own numbers, and compares them in its own way.

WaypointGroup, WaypointGroupAtSpeed, Path, PathWithSpeed, EnterSight, and UnitStopped and SpellCastAnswer where they carry one, share one count per unit, from -1. A client takes a statement whose number is equal to the unit’s or ahead of it; a number 2³⁰ or more behind counts as ahead, so the count can wrap. A group of movements carries one syncId for every unit in it. A server MUST give each statement about a unit a number equal to or ahead of the last it gave that unit.

A statement a client does not take changes nothing; what follows it still applies.

For replication, a server MUST give each batch carrying a unit a number greater than the last batch carrying that unit, and MUST NOT give one 0. A server SHOULD give every batch a number of its own, so that a TransientAck names one batch.

A client sends a view report again until a server answers with its number, twice the round trip time plus 1/30 of a second apart. A server MUST answer each view report with CameraAck, carrying its number.

What a client answers

A client sends these answers when it plays a match, not while it plays back a stream.

Space

How positions, distances and directions are carried, whichever system carries them, and what a map gives that nothing on the wire carries.

Units and axes

Positions and distances are in world units. The ground is the plane of x and z, and y is height. A field that carries a position on the ground carries x and z; one that carries a point in the world carries x, y and z. Where a message leaves height out, a receiving end takes it from the ground beneath.

A position travels as a 32-bit float on each axis unless its definition says otherwise. Where the paths of Movement and MovementAtSpeed are compact, they carry their points as integers measured from the map’s origin, and Movement says how those points are worked out.

Directions

A direction is carried as a vector, not as an angle:

• A unit’s facing in the movement state EnterSight carries is a pair along the ground, x and z.
• UnitStopped, MissileState, a particle’s facing and a view’s direction in Camera carry x, y and z.
• FaceDirection carries x, y and z, and turns the unit to face along them.

FaceDirection turns the unit over the time it gives where its flags say so, and at once otherwise.

A champion carries no facing of its own when created.

A champion faces as its map’s table of spawn positions says (see CreateChampion).

CreateNeutral carries a point to face rather than a direction: the monster faces from where it stands toward that point, or along +z where the two are the same.

A prop of scenery carries angles instead: MapProp gives its turn as pitch, yaw and roll, in degrees, where yaw 0 faces +z and yaw 90 faces +x. For an active prop, the same three fields are a direction vector.

Maps

VersionSync names the map to load by number. A client takes a map’s buildings (see Objects and identifiers), spawn positions and path origin (see Movement) from its own data (see The client’s data), and can load only a map it has data for.

The maps a client has data for include these:

Time

Which clocks a match runs on, and which of them each time on the wire is measured against.

How a time is carried

A time is in seconds, as a 32-bit float, unless its definition says otherwise. A field is either a moment, read against a clock, or a duration, which starts when the message arrives. Every definition says which.

Exceptions:

• Paused carries the time left in a hold as a whole number of seconds.
• A stream’s chunk and key frame intervals (StreamMetadata) are in milliseconds.

The match clock

The match runs on a server’s clock, which counts seconds from 0 as play begins. ClockSync states where it stands, and a client sets its own clock to that, plus its allowance for how late the statement arrived. A client answers with ClockReply, from which a server measures the round trip. A server can report the round trip it measured with ClockConvergence.

A server sends ClockSync with 0 as play begins (see Joining a match), and again whenever it means a client’s clock to catch up with its own.

A client shows the match’s time counted from the moment on the match clock at which the match began.

MatchStarted gives that moment, and a client shows zero while the match clock is before it.

Moments on the match clock include:

• when a monster arrives (CreateNeutral’s spawnAt, where it carries one);
• when a prop’s animation starts (MapPropChanged, where it carries one);
• when an assisting unit last dealt damage (ClientEvent);
• when a champion’s passive comes off cooldown, where a client is told it (see Replication).

A server MUST state each of these on the clock it sends in ClockSync.

A stream’s clock

A watching client plays a stream against a clock of the stream’s own, which the stream’s records set (see Watching a match).

Sides and slots

Values many systems share: which side something is on, and how a unit’s spell, item and effect slots are numbered.

Sides

A side is 100 or 200, for the two sides that play, or 300 for what belongs to neither, such as a monster of no side. Where a field takes 0, it names no side; its note says what that means. A few fields carry a side in another form, and their notes say which.

Roster lists the players of each side, and a player’s place in that list is their seat (see Objects and identifiers).

Spell slots

A champion has two books of spells. Its own book holds these slots:

Its summoner book holds the two summoner spells, in slots 0 and 1.

A message that names a spell slot either carries a flag, set for the summoner book and clear for the champion’s own, or names the champion’s own book only. A cast’s description (SpellCast) carries no flag: the spell’s own data says whether it is a summoner spell.

A cast’s slot also takes 64 to 72 for a basic attack and 73 to 81 for a critical one.

A cast’s slot also takes 255, for a cast from no slot.

A server MUST NOT name a champion book slot beyond the book’s last slot.

Inventory slots

A champion’s inventory holds the six items a player sees and uses in slots 0 to 5, and further slots after them up to its last.

An item is cast from the spell slot four above its inventory slot, and moving an item moves its spell with it. A server MUST NOT name an inventory slot beyond the inventory’s last slot.

Slot 6 holds the trinket, slot 7 the item recalling uses, and slots from 8 on items held for the match’s own purposes, which nothing a player sees shows. A client asks to swap only slots 0 to 6 (SwapItems).

Effect slots

Adding an effect to a slot replaces whatever held it, and removing one empties the slot whatever its name.

Each unit has 64 slots for the effects it carries, 0 to 63. A slot outside that range does nothing.

The client’s data

What a server needs that no message carries, and takes from the files a client installs: the buildings and spawn points of a map, the ground units walk on, and the figures of champions, items and spells. A server SHOULD take its figures from these files: a client draws a match from them, and figures from elsewhere disagree with what it shows.

What a server reads

• The buildings of a map: the names a client knows its turrets, inhibitors and nexuses by, from which Objects and identifiers works out the identifier of each.
• The spawn points: where each side’s champions begin.
• The ground: the grid a map’s units walk on, which a server needs to find paths.
• The figures: each champion’s base statistics, each item’s price and what it is built from, and each spell’s cooldowns, costs and ranges, which a server states through replication and SpellCast.

Movement takes the origin of a path from the ground.

A client installs its files under one root, with the paths below; an install that packs them into archives keeps the same paths inside.

Buildings. LEVELS/Map1/Scene/room.dsc lists a map’s scene objects, one line each: a file name and a quality number. Each object’s own file sits beside it and gives its name. A client creates no object from a name holding _Destroyed or _FB. On map 1 the names run Turret_T<side>_<lane>_<number> for a lane turret, Barracks_T<side>_<lane>1 for an inhibitor and HQ_T<side> for a nexus, side 1 for Order and 2 for Chaos and lanes L, C and R, with a shrine turret for each side; the numbers differ between the sides, and a server MUST take the names from the files.

Objects and spawn points. A champion begins at its side’s spawn point, __Spawn_T1 for Order and __Spawn_T2 for Chaos.

The ground. A client walks units on LEVELS/Map1/AIPath.aimesh_ngrid, a binary grid. Its layout is unspecified.

The figures. Each is an inibin file: a champion’s base statistics in DATA/Characters/<Champion>/<Champion>.inibin; an item, its price among its figures, in DATA/Items/<id>.inibin; and summoner, item and shared spells in DATA/Spells/<Spell>.inibin.

Joining a match

What passes between a client and a server from connection until play begins, in order.

Starting a client

A client learns where to connect from its command line. It takes three arguments it needs nothing in, which can be empty, and then a fourth holding four words separated by single spaces: the server’s IPv4 address, its UDP port, the key (see Transport), and the player id the client registers as. The client connects to that address and port, registers as that player, and enciphers its proof under that key.

Registering

A client’s first payload is Register, on the registration channel. The note on Registered says what a server answers with: one answer for every seat.

A client knows the answer meant for it by the player id it registered as, not by the client id, and takes the client id that answer carries as its own. Every other answer tells it which client id stands for which player.

A client waits 30 seconds for the answer naming its own player id. Then it offers its player to wait another 30 seconds or to give up, and leaves on giving up.

Asking whether a server is ready

A client then sends QueryStatus over and over. A server MUST answer each one with QueryStatusAnswer, at least until it has answered that it is ready. While the answers say the server is not ready, a client stays on a black screen and keeps asking. A server that needs time before a match can begin answers that it is not ready until it is.

A server MUST also answer each QueryStatus that comes after its first ready answer.

Stating a build

Once an answer says the server is ready, a client sends ClientVersion once. A server answers with VersionSync, and a client loads only where its agreement says the builds agree.

VersionSync names the map to load and everyone at the match.

Taking a seat

Straight after VersionSync, a client sends JoinSide on the roster channel. A server answers with one Roster, then a SeatName and a SeatChampion for each seat a player holds.

Loading

A client reports how far loading has got with LoadingProgress, repeatedly through loading. A server answers each report with SeatLoadProgress on the transient channel, carrying the report’s figures under the seat that reported. A client goes on reporting after its progress reaches 100, until play begins.

A client waits on no other seat. SpawnStart, SpawnEnd and StartGame are what move a client on, and StartGame alone ends its loading. A server that means its players to begin together sends StartGame to none of them until every client has sent ClientReady.

A client writes all ones where its player id goes in LoadingProgress.

A server MUST put the seat’s player id in SeatLoadProgress: the loading screen shows a seat’s card from the VersionSync seat with that id.

The spawn run

Once a character is settled, a client sends CharacterSelected, once.

Until it sends CharacterSelected, a client drops every message but VersionSync, QueryStatusAnswer, MatchIdentity, SeatLoadProgress and GameEnded, apart from what arrives on the registration and roster channels, and keeps nothing it drops for later. A server MUST NOT send any of the spawn run before CharacterSelected arrives.

A client can send CharacterSelected before its progress reaches 100.

A server answers with SpawnStart, states everything on the field as play opens, and closes the run with SpawnEnd. A run carries:

• for each seat, CreateChampion followed by Loadout;
• for each turret, a CreateTurret and a Replication batch of its values;
• for each inhibitor and nexus, an EnterSight, and a Replication batch on a map whose buildings replicate (see Replication);
• a RegionAdded for each region, and a MapProp for each prop;
• at a server’s choice, an EnterLocalSight for any of those units.

A turret’s CreateTurret can come on its own or inside the EnterSight that brings the turret into view.

A client takes these in any order within the run.

A run MUST carry at least SpawnStart, the CreateChampion carrying the client’s own client id, and SpawnEnd. Given only those, a client still enters play, showing its champion’s portrait, health, resource and spells. It draws the champion on the map only once an EnterSight places it there, with its name and health bar over it.

A client’s shop stays empty until its own champion’s Loadout arrives (see The shop).

A client answers each Replication batch with a TransientAck naming that batch’s syncId. It sends one answer for each batch, in the order the batches came, including a batch that repeats the syncId of the batch before it.

A client answers the batches the run carried once SpawnEnd arrives.

Starting play

A client sends ClientReady after SpawnEnd and after its answers to the run’s batches, while it is still reporting its loading. A server MUST answer with StartGame, and later sends MatchStarted, with other messages free to come between them; MatchStarted carries 0 (see Time).

A client whose connection drops before play begins ends rather than connecting again. A server follows StartGame with a ClockSync, and a client enters play once it has both. The first ClockSync carries 0.

Messages

Each message of this system in this book, with each layout it has across the book’s patches and every note its definition carries. A layout is the message’s body, after the header its channel’s family puts in front (see Messages).

Units

How a server puts objects on the field and takes them away: champions, minions, neutral monsters, turrets, pets, markers and props. What a unit then does is in Movement, Combat and Spells, and what it is worth in Replication.

Every object is named by a net id, and Objects and identifiers says what removes each kind of object.

Creating

Each kind of object has its own message:

• a champion, CreateChampion, which, carrying the client’s own client id, also makes that champion the client’s own; a bot’s champion, the same CreateChampion naming no client, or SpawnBot;
• a minion sent out from a side’s barracks, SpawnFromBarracks, and a unit like one, such as a ward, SpawnUnit;
• a monster of no side, CreateNeutral; a pet, SpawnPet;
• a turret, CreateTurret (The client’s data says how it names one), and a turret of the server’s choosing, SpawnTurret;
• an object that follows a unit, CreateFollower, and a change to what it follows, FollowerMaster;
• an unseen marker, SpawnMarker, which other messages can name and MarkerMoved moves;
• a prop, a thing that stands on the map and is looked at, MapProp, and a change to one, MapPropChanged.

Several of these arrive on their own or inside the EnterSight that brings the unit into view (see Vision): a client takes either.

CharacterPreload has a client load a character’s art ahead of need.

Changing and removing

TeamChanged moves a unit to another side, and ChampionRemoved takes a champion out of the world. A unit’s death is in Combat.

Bots

A server can tell a client what a bot is thinking (BotDebug), weighing (BotTargets) or doing (BotState). None of them changes what a player sees.

Messages

Each message of this system in this book, with each layout it has across the book’s patches and every note its definition carries. A layout is the message’s body, after the header its channel’s family puts in front (see Messages).