Launcher/Client Protocol
Last updated
Last updated
This page describes the communication protocol employed by launcher.exe, Tl.exe, and TERA.exe.
C/C++-like primitive types and structs will be used.
Integers (uint8_t, int8_t, uint16_t, int16_t, etc) are little endian.
Characters (i.e. char8_t and char16_t) are UTF-8 and UTF-16 respectively, and little endian.
Strings (i.e. u8string and u16string) are a series of valid char8_t and char16_t characters respectively, followed by a NUL character.
Fields are laid out in the declared order with no implied padding anywhere.
Note that strings are not always NUL-terminated. For this reason, the document will explicitly call out whether a NUL terminator is present.
The role of each program is as follows:
launcher.exe: The publisher-specific game launcher which performs authentication and server list URL resolution. Serves requests from Tl.exe and receives game events.
Tl.exe: The (mostly) publisher-agnostic game launcher which requests authentication data and the server list URL from launcher.exe. Serves requests and forwards game events from TERA.exe.
TERA.exe: The actual game client. Sends requests and game events to Tl.exe.
These programs all communicate via , specifically . The dwData field specifies the message ID, while lpData and cbData contain the payload pointer and length.
Tl.exe -> launcher.exe MessagesMessages sent between Tl.exe and launcher.exe consist of text encoded as UTF-8. A NUL terminator is present in most messages, but not all. Responses from launcher.exe should always use the same message ID that Tl.exe used in the corresponding request message. Notably, only the Hello Handshake and Game Event Notification messages have a static ID; the request messages use a message counter as the message ID, so the contents must be parsed to understand them.
0x0dbadb0a)The protocol starts off with a handshake sent from Tl.exe. This message contains the NUL-terminated string Hello!!.
0x0)^csPopup\(\)$: Signals that launcher.exe should open the customer support website (e.g. in the default Web browser).
^gameEvent\((\d+)\)$: Indicates some kind of notable action taken by the user in the game. The value in parentheses is a code specifying the type of event; the possible values are documented in the section on TERA.exe messages.
^endPopup\((\d+)\)$: Indicates that the client has exited. The value in parentheses is an exit reason code (not the same as the process exit code); the possible values are documented in the section on TERA.exe messages.
^promoPopup\(\d+\)$: The exact purpose of this notification is currently unknown.
launcher.exe should not respond to these messages.
Tl.exe will request the server list URL from launcher.exe. This message does not have a static message ID. The message contains the NUL-terminated string slsurl.
launcher.exe should respond with the NUL-terminated server list URL.
gamestr is only sent when the game is initially launched. This request asks for the full authentication data.
ticket, last_svr, and char_cnt are only sent when returning to the server list from an arbiter server.
ticket: Requests the authentication ticket. This can be the same ticket as before, but launcher.exe may also choose to authenticate anew and retrieve a fresh ticket.
last_svr: Requests the ID of the last server the the account connected to.
char_cnt: Requests character counts for each server in the server list.
launcher.exe should respond with the NUL-terminated JSON payload.
Some properties are only required depending on the message:
gamestr: All properties are required.
ticket: The ticket property is required.
last_svr: The last_connected_server_id property is required.
char_cnt: The chars_per_server property is required.
result-message, account_bits, access_level, and user_permission are completely optional.
Tl.exe will request a URL to be opened in the client's embedded Web browser. This message does not have a static message ID and is not NUL-terminated.
The message can be described by the regular expression ^getWebLinkUrl\((\d+),(.*)\)$. The first group is the ID of a UIWindow node under the CoherentGTWeb data center sheet, and the second group is a set of arguments specific to that URL.
launcher.exe should respond with a URL to be opened (without a NUL terminator), or an empty payload to reject the request.
TERA.exe -> Tl.exe MessagesMessages sent between TERA.exe and Tl.exe use a simple binary protocol. All messages have static message IDs; responses have different IDs from requests.
0x1)TERA.exe will request the (game) account name from Tl.exe.
0x2)Tl.exe should respond with the account name.
account_name is the name of the game account. It is not NUL-terminated.
0x3)TERA.exe will request the session ticket from Tl.exe.
0x4)Tl.exe should respond with the session ticket.
session_ticket is the authentication session ticket. It is not NUL-terminated.
0x5)TERA.exe will request the server list from Tl.exe.
sorting specifies how Tl.exe should sort the server list. Valid values are as follows:
A few notes on sorting:
The sort should be stable.
LAUNCHER_SERVER_LIST_SORT_CRITERIA_NONE indicates that Tl.exe is free to sort the list arbitrarily.
The resultant list should be maintained between requests and further sorted on each request, unless LAUNCHER_SERVER_LIST_SORTING_NONE is sent to reset the sorting.
If the same sorting is requested multiple times and is any sorting other than LAUNCHER_SERVER_LIST_SORT_CRITERIA_NONE, the list should simply be reversed without applying sorting.
0x6)Server List Structures
The server list response can be described with the following message definitions:
A few notes on these definitions:
They will not work correctly as proto3 due to required semantics.
bytes fields are really u16string without NUL terminators.
id must be a positive (non-zero) value.
port should be in the uint16_t range.
available is really a bool, so only the values 0 and 1 are allowed.
Either address or host must be set; not neither and not both.
For address, a value of 0 has 'not set' semantics since the field is not marked optional.
sort_criterion should be the LauncherServerListSortCriteria value that was sent in the request.
0x7)TERA.exe will notify Tl.exe when entering the lobby (i.e. successfully connecting to an arbiter server) or when entering the world on a particular character.
The two cases can be distinguished by looking at the payload length.
character_name is the NUL-terminated name of the character that the user is entering the world on.
Create Room (0x8)
Join Room (0xa)
Leave Room (0xc)
Set Volume (0x13)
Set Microphone (0x14)
Silence User (0x15)
These messages were only present in some regions and were likely never actually used. It is currently unknown what their payloads contain.
The following responses exist for the above TeamSpeak requests:
Create Room Result (0x9)
Join Room Result (0xb)
Leave Room Result (0xd)
0x19)TERA.exe asks Tl.exe to open a website in the default Web browser.
id specifies the kind of website that should be opened. The possible values are currently unknown.
0x1a)This request is the TERA.exe equivalent of the request sent by Tl.exe to launcher.exe.
id refers to a UIWindow node under the CoherentGTWeb data center sheet.
arguments specifies the NUL-terminated arguments specific to the URL.
0x1b)id is the same value that was sent in the request.
url is the NUL-terminated URL to open. It can be the empty string or the special string | to indicate that no URL should be opened.
0x3e8)TERA.exe will notify Tl.exe that it has launched.
source_revision is the SrcRegVer value from the client's ReleaseRevision.txt file.
The meaning of unknown_1 is currently unknown.
windows_account_name is the NUL-terminated name of the current Windows user account.
0x3e9 - 0x3f8)TERA.exe will occasionally notify Tl.exe of various notable actions taken by the user.
event specifies the kind of event that occurred. Valid values are as follows:
0x3fc)TERA.exe will notify Tl.exe that it is exiting.
length is the length of the payload. It must be 12.
code is the exit code of the TERA.exe process. This can be 0 or 1.
reason provides a more specific exit reason. Some known values are as follows:
(The above enumeration is an incomplete list.)
0x3fd)TERA.exe will notify Tl.exe that it has crashed (e.g. because of a memory access violation). Note that, since a crash could mean things are arbitrarily broken, this message may not be produced if the crash is sufficiently severe.
details contains various details about the crash such as the instruction pointer and exception type. It is not NUL-terminated.
0x3fe - 0x400)0x3fe)TERA.exe will notify Tl.exe that the anti-cheat module is starting.
0x3ff)TERA.exe will notify Tl.exe that the anti-cheat module has successfully started.
0x400)TERA.exe will notify Tl.exe that the anti-cheat module failed to start.
error contains the error code from the anti-cheat module.
0x401)TERA.exe asks Tl.exe to open the customer support website in the default Web browser.
0x403)The exact purpose of this message is currently unknown.
launcher.exe should respond with a NUL-terminated Hello!! or Steam!! to indicate the method of authentication in use. The former uses classic authentication while the latter uses . (Steam authentication will not be documented here.)
Tl.exe will occasionally notify launcher.exe of various game events sent by TERA.exe. The format of these messages can be described with the following :
The Web server at the URL should be prepared to receive an request, potentially with a (which can be ignored). The response should use the . Note that Tl.exe does not support .
The response received from the server list URL should be in format. It can be described with the following schema:
Tl.exe will request -encoded authentication data from launcher.exe. This message does not have a static message ID. The message contains one of several NUL-terminated strings.
The authentication JSON response can be described with the following definition:
Tl.exe should respond with the server list encoded with .
There is a set of requests for interacting with :
TERA.exe will notify Tl.exe of various events relating to the anti-cheat module (e.g. or ). Note that only some regions have a client build with an anti-cheat module.