SimTX API/Packets/Banner: Difference between revisions
Protocol v25 reference: Banner Tag: Removed redirect |
Remove development history and server internals |
||
| Line 38: | Line 38: | ||
* Hide the banner when <code>text</code> is empty. | * Hide the banner when <code>text</code> is empty. | ||
* Hide it at <code>expires_at_ms</code>. The server does not send a clearing banner when a notice expires. | * Hide it at <code>expires_at_ms</code>. The server does not send a clearing banner when a notice expires. | ||
* A <code>BANNER_LEVEL_BAN_NOTICE</code> banner is sent to the control sessions of an address that has just been banned. Those control sessions stay connected | * A <code>BANNER_LEVEL_BAN_NOTICE</code> banner is sent to the control sessions of an address that has just been banned. Those control sessions stay connected; new game connections from the address are refused with <code>HELLO_STATUS_IP_BANNED</code>. | ||
* The server also posts short automatic notices when it is overloaded. They clear themselves after about a minute. | * The server also posts short automatic notices when it is overloaded. They clear themselves after about a minute. | ||
* Banners may arrive between any other frames. Current servers send them on control sessions only; a client of another role that receives one may show or ignore it. | * Banners may arrive between any other frames. Current servers send them on control sessions only; a client of another role that receives one may show or ignore it. | ||
== Example == | == Example == | ||
Complete frames, including the varint length prefix | Complete frames, including the varint length prefix. | ||
'''<code>banner_ban_notice</code>''' (server to client, 36 bytes): | '''<code>banner_ban_notice</code>''' (server to client, 36 bytes): | ||
Latest revision as of 17:16, 24 October 2026
| Frame | ServerFrame, field 4
|
|---|---|
| Member | banner
|
| Direction | Server → client |
| Session | Control |
| Roles | Sent on control sessions. Clients of every role should accept it. |
| Permission | None |
| Defined in | control.proto
|
Banner carries a server-wide notice for the client to display, such as planned maintenance, a performance warning or a ban notice. The server sends it when a control session starts, if a notice is active, and pushes it to every control session whenever a notice is set, replaced or cleared.
Definition[edit | edit source]
message Banner {
BannerLevel level = 1;
string text = 2;
int64 expires_at_ms = 3; // 0 = no expiry
}
Fields[edit | edit source]
| # | Field | Type | Description |
|---|---|---|---|
| 1 | level |
BannerLevel | BANNER_LEVEL_INFO (0) or BANNER_LEVEL_BAN_NOTICE (1). Show unknown levels as information.
|
| 2 | text |
string |
Notice text, at most 512 characters. Empty clears the current notice. |
| 3 | expires_at_ms |
int64 |
Hide the notice after this time, Unix ms. 0 = no expiry. |
Usage[edit | edit source]
- Show the text prominently, replacing any earlier banner. Each Banner supersedes the previous one.
- Hide the banner when
textis empty. - Hide it at
expires_at_ms. The server does not send a clearing banner when a notice expires. - A
BANNER_LEVEL_BAN_NOTICEbanner is sent to the control sessions of an address that has just been banned. Those control sessions stay connected; new game connections from the address are refused withHELLO_STATUS_IP_BANNED. - The server also posts short automatic notices when it is overloaded. They clear themselves after about a minute.
- Banners may arrive between any other frames. Current servers send them on control sessions only; a client of another role that receives one may show or ignore it.
Example[edit | edit source]
Complete frames, including the varint length prefix.
banner_ban_notice (server to client, 36 bytes):
23 frame length 35
22 21 banner (Banner), 33 bytes
08 01 level = 1 (BANNER_LEVEL_BAN_NOTICE)
12 16 54 68 69 73 20 61 64 64 … text = "This address is banned"
18 80 F1 DE BA 97 34 expires_at_ms = 1793003600000