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 1.0.0.130 up to, not including, 3.01.0.1, in 23 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.

Stock ENet 1.2.5 serves a client once its transmission unit is clamped (see below). The header and the commands are the release’s own.

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 every range of this book

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 asks for 7 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.

An argument longer than sixteen characters holds the key in base64, and the key is the first sixteen bytes it decodes to. An argument of sixteen characters or fewer is the key as it stands.

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 1.0.0.130–1.0.0.151

In 1.0.0.152–3.1.0.0

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.

A client unwraps a container on any channel.

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

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 1.0.0.130–1.0.0.151

The game family:

The session family:

The registration family:

The chat family:

No header.

In 1.0.0.152–3.1.0.0

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.

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

A client takes a client id only from 0 to 252, and leaves on any other.

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.

A client acts on that Registered alone and ignores every other, so it pairs no other player’s player id with a client id.

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 create message carries a node beside the object’s net id.

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:

Every object a map places carries the identifier its name gives, turrets, navigation points and props among them.

A name holding _Destroyed or _FB gives no identifier.

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.

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

A client removes a region once its lifetime reaches 0, so a region given a lifetime of 0 does not last.

RegionRemoved for a region a client does not hold does nothing.

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.

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.

A byte from 128 to 255 enters the hash as its value less 256, worked in 32 bits, rather than as itself.

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 also answers each Path and PathWithSpeed, taken or not, with a WaypointAck carrying its syncId.

That answer lists no units but leaves its count of units unset, so a server MUST NOT rely on the count.

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 along x and z alone, and leaves it as it is where both are 0.

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.

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 client takes the round trip ClockConvergence reports into its allowance for lateness.

Each ClockConvergence sets a client’s allowance to 0.8 times what it was plus 0.1 times the round trip it reports.

The allowance starts at 0, and nothing but ClockConvergence changes it: a client that has had none takes ClockSync as it stands. A server SHOULD send ClockConvergence, or each ClockSync sets a client’s clock behind by the time it took to arrive.

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’s match clock does not run until the first ClockSync arrives, which sets it. After that it runs on the client’s own timer, and a later ClockSync only corrects it, however long a server leaves between them.

GameSpeed sets the pace of the match clock, and a hold sets the pace to 0 until play resumes. A server that runs a match at other than normal speed MUST send GameSpeed with that speed, or a client’s match clock runs apart from its own.

A GameSpeed that arrives during a hold takes effect as play resumes.

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

MatchStarted gives that moment. Until it arrives, a client takes the match clock’s reading as its game loop runs, and a MatchStarted arriving later replaces it. While the match clock is before that moment, a client shows a negative time.

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 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.

A client asks to swap only slots 0 to 5 (SwapItems).

A champion’s inventory ends at slot 37. A client ignores a RemoveItemAnswer, InventorySlot, ItemAdded, ItemUsed or ItemCharges naming a slot above 37. A server MUST NOT name an inventory slot above 37.

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.

A word a name holds anywhere says what the object is, not only its opening, the first match winning: a minion spawner’s Spawn_Barracks is tested before Barracks, which makes an inhibitor, and HQ_ makes a nexus and Turret a turret.

Each object’s file is .sco as text or .SCB as binary, and gives its name on its Name= line.

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

The spawn points, the navigation points and the marker of the level’s size are scene objects, listed in room.dsc like the buildings.

A champion begins at its side’s spawn point moved by an offset from DATA/Characters/HeroSpawnOffsets.inibin, read from the section Order<n> or Chaos<n> under the keys Pos<i> and Facing<i>, where i is one more than CreateChampion’s spawn index. A spawn index of 6 or more begins the champion on the spawn point itself.

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

The grid’s name is the map’s own, AIPath.aimesh with _ngrid after it: no setting of the mode chooses it.

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.

Map 1 adds LEVELS/Map1/Items.inibin to the items, and figures for a whole mode are in DATA/Globals/, such as CLASSIC_Stats.inibin and HealthGain.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.

Any whitespace separates the words of the fourth argument. A client whose command line holds no double quote takes the command line it saved on an earlier run instead, and one holding .rep anywhere plays a replay rather than connecting.

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 client stops asking once an answer says the server is ready, and a query it sends after that answer needs none.

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.

The loading screen

What a client draws while it loads comes from what it has been sent by then (see the spawn run below for what it takes before CharacterSelected).

A player’s card is built from several messages. Its place on the screen is that seat’s place in the Roster, and its name is that player’s SeatName. The registration answers (Registered) pair each player with a client id, and the latest SeatLoadProgress for that client gives the card its progress and, on the client’s own card only, its ping. The first SeatLoadProgress after the player’s SeatChampion sets the card up: its portrait and the champion’s name, from that SeatChampion’s champion and skin, then everything else from the VersionSync seat whose player id the SeatLoadProgress names. A card with no SeatChampion yet shows a black portrait, and one with no registration or no SeatLoadProgress yet says it is not connected. A later SeatChampion does not change a card already set up.

The spawn run

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

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 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 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 a batch as soon as it arrives, within the run or not, and never answers one naming a unit it does not hold.

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 sends ClientReady as soon as SpawnEnd arrives, and StartGame alone moves it into play.

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.

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).

Vision

What a client can see, and how a server tells it. A client draws what a server says it sees and nothing else: the fog of war a client draws is only a picture, and what lies inside it is whatever the server has brought into view.

Bringing a unit into view

A server brings a unit into what a client’s side can see with EnterSight.

EnterSight also states the unit’s items.

A client does not draw a champion that no EnterSight has placed: given only its CreateChampion, a client shows the champion’s portrait and spells and nothing on the field. One EnterSight after the CreateChampion draws it, with its name and health bar over it.

EnterLocalSight brings a unit into what one client alone can see. EnterTeamSight brings an object into the view of a whole side.

EnterLocalSight states the unit’s health.

Losing sight

LeaveSight and LeaveTeamSight take a unit out of the matching view, and leave it held (see Objects and identifiers). Particles come into and leave a side’s view with ParticleEnterTeamSight and ParticleLeaveTeamSight.

Regions

A region is a patch of ground with sight of its own, which can reveal hidden units within it. A server places one with RegionAdded or fastens one to a unit with RegionAttached, moves it with RegionMoved and takes it away with RegionRemoved; Objects and identifiers says how regions are named and when one ends. A region granting sight has a client clear its map’s cover over it.