KTag BLE Advertisement Specification
Version 0.14, November 7, 2026
KTag devices communicate by broadcasting Bluetoothยฎ Low Energy (BLE) advertisements. Each advertisement carries one KTag packet in its Manufacturer Specific Data, and this page describes the format of every type of KTag packet. It replaces the KTag Beacon Specification spreadsheet.
Every KTag packet is a single BLE advertising data (AD) structure of type Manufacturer Specific Data, 31 bytes long. The first ten bytes are the same for every packet type:
| 0/8 | 1/9 | 2/A | 3/B | 4/C | 5/D | 6/E | 7/F |
| 0x00 | Length | Manufacturer Specific Data | Company: Other | KTag Packet Indicator |
| 0x1E | 0xFF | 0xFF | 0xFF | 0x4B โKโ | 0x54 โTโ | 0x61 โaโ | 0x67 โgโ |
| 0x08 | KTag Packet Type | Event Number | | | | | | |
| (varies) | 0xXX | | | | | | |
| 0x10 | | | | | | | | |
| | | | | | | | |
| 0x18 | | | | | | | | |
| | | | | | | | |
| Offset |
Size |
Field |
Value |
| 0x00 |
1 |
Length |
0x1E (30 bytes follow) |
| 0x01 |
1 |
AD Type |
0xFF (Manufacturer Specific Data) |
| 0x02โ0x03 |
2 |
Company Identifier |
0xFFFF (Other) |
| 0x04โ0x07 |
4 |
KTag Packet Indicator |
0x4B 0x54 0x61 0x67 (ASCII KTag) |
| 0x08 |
1 |
KTag Packet Type |
See Packet Types |
| 0x09 |
1 |
Event Number |
See below |
Bytes 0x0A to 0x1E (21 bytes) depend on the packet type.
The Event Number tells apart logical instances of a packet. A device repeats the same advertisement many times so that it's heard reliably, and a receiver uses the Event Number to act on each one only once. A device increments the Event Number whenever it sends new data in a packet of that type.
Event Number vs. Event ID
Don't confuse the Event Number with the Event ID of the EVENT packet. Event IDs identify types of system-level events, while Event Numbers distinguish one packet from the next.
Packet Indicator
| Indicator |
Format |
KTag (0x4B 0x54 0x61 0x67) |
Cleartext |
KShh (0x4B 0x53 0x68 0x68) |
Encrypted (reserved for future use) |
Packet Types
Data Types
- Multi-byte values are little-endian (least significant byte first).
SInt8, SInt16 and SInt32 are signed (two's complement); UInt8, UInt16 and UInt32 are unsigned.
- A color is a 32-bit value
0xBBRRGGBB: brightness, red, green, blue. Because it's sent little-endian, the bytes go out in the order BB GG RR BB: blue first and brightness last.
- A BD_ADDR is a 6-byte Bluetooth device address, sent least significant byte first: the reverse of the order in which it's usually written. For example, the address
AA:BB:CC:DD:EE:FF is sent as FF EE DD CC BB AA. A target BD_ADDR of FF:FF:FF:FF:FF:FF targets all devices.
- Unused bytes are sent as
0xFF. Receivers ignore them, so that a later version of this specification can give them a meaning.
0xXX in the tables means the value varies.
0x01 Instigate Game
Sent to start a game.
| 0/8 | 1/9 | 2/A | 3/B | 4/C | 5/D | 6/E | 7/F |
| 0x00 | Length | Manufacturer Specific Data | Company: Other | KTag Packet Indicator |
| 0x1E | 0xFF | 0xFF | 0xFF | 0x4B โKโ | 0x54 โTโ | 0x61 โaโ | 0x67 โgโ |
| 0x08 | KTag Packet Type | Event Number | Game Length (ms) | Time Remaining until Countdown (ms) |
| 0x01 | 0xXX | 0xXX | 0xXX | 0xXX | 0xXX | 0xXX | 0xXX |
| 0x10 | Time Remaining until Countdown (ms) (cont.) | | | | | | |
| 0xXX | 0xXX | 0xFF | 0xFF | 0xFF | 0xFF | 0xFF | 0xFF |
| 0x18 | | | | | | | | |
| 0xFF | 0xFF | 0xFF | 0xFF | 0xFF | 0xFF | 0xFF | |
| Offset |
Size |
Field |
Type |
Notes |
| 0x0Aโ0x0D |
4 |
Game Length (ms) |
UInt32 |
0 means an untimed game. |
| 0x0Eโ0x11 |
4 |
Time Remaining until Countdown (ms) |
UInt32 |
|
| 0x12โ0x1E |
13 |
Unused |
|
|
0x02 Event
Signals a system-level event to one device, or to all of them.
| 0/8 | 1/9 | 2/A | 3/B | 4/C | 5/D | 6/E | 7/F |
| 0x00 | Length | Manufacturer Specific Data | Company: Other | KTag Packet Indicator |
| 0x1E | 0xFF | 0xFF | 0xFF | 0x4B โKโ | 0x54 โTโ | 0x61 โaโ | 0x67 โgโ |
| 0x08 | KTag Packet Type | Event Number | Target BD_ADDR |
| 0x02 | 0xXX | 0xXX | 0xXX | 0xXX | 0xXX | 0xXX | 0xXX |
| 0x10 | Event ID | Event Data |
| 0xXX | 0xXX | 0xXX | 0xXX | 0xXX | 0xXX | 0xXX | 0xXX |
| 0x18 | | | | | | | | |
| 0xFF | 0xFF | 0xFF | 0xFF | 0xFF | 0xFF | 0xFF | |
| Offset |
Size |
Field |
Type |
Notes |
| 0x0Aโ0x0F |
6 |
Target BD_ADDR |
BD_ADDR |
FF:FF:FF:FF:FF:FF targets all devices. |
| 0x10โ0x13 |
4 |
Event ID |
UInt32 |
See below. |
| 0x14โ0x17 |
4 |
Event Data |
UInt32 |
Meaning depends on the Event ID. |
| 0x18โ0x1E |
7 |
Unused |
|
|
| Event ID |
Event |
Event Data |
Description |
| 0 |
No Event |
Unused |
Reserved. Devices take no action when they receive this event. |
| 1 |
Configure |
Unused |
The target device(s) need configuration. |
| 2 |
Configured |
Unused |
Configuration of the target device(s) is complete. |
| 3 |
Wrapup Complete |
Next State |
Wrapup is complete for the target device(s), which should proceed to the Next State. |
| 4 |
Game Over |
Unused |
The game is over. |
| 5 |
Quiet |
Duration (ms) |
The target device(s) stop BLE advertising for the given duration, or until they receive an Unquiet. A duration of 0 means stay quiet until an Unquiet. A new Quiet during a quiet period restarts the timer with the new duration. A quiet device still listens: when it receives a PARAMETERS Request Parameter Change addressed to it, it advertises its reply (for about 3 seconds in SystemK), then goes quiet again for the rest of the period. SystemK also ends a quiet period when the device leaves the Configuring state or starts playing. |
| 6 |
Unquiet |
Unused |
The target device(s) may resume BLE advertising. |
| 7 |
Force State |
Next State |
The target device(s) proceed immediately to the Next State. This may ruin active games, or cause a device to reprogram itself. Use with care! |
The Next State values are the SystemK top-level states.
0x03 Tag
Sent when a device tags (or heals) another device over BLE.
| 0/8 | 1/9 | 2/A | 3/B | 4/C | 5/D | 6/E | 7/F |
| 0x00 | Length | Manufacturer Specific Data | Company: Other | KTag Packet Indicator |
| 0x1E | 0xFF | 0xFF | 0xFF | 0x4B โKโ | 0x54 โTโ | 0x61 โaโ | 0x67 โgโ |
| 0x08 | KTag Packet Type | Event Number | Tx Power Level | Protocol | Team ID | Player ID | Damage |
| 0x03 | 0xXX | 0xXX | 0xXX | 0xXX | 0xXX | 0xXX | 0xXX |
| 0x10 | Color | Target BD_ADDR |
| 0xXX | 0xXX | 0xXX | 0xXX | 0xXX | 0xXX | 0xXX | 0xXX |
| 0x18 | Target BD_ADDR (cont.) | Splash Target Teams | Splash Min. RSSI | Hops Remaining | Splash ID | |
| 0xXX | 0xXX | 0xXX | 0xXX | 0xXX | 0xXX | 0xXX | |
| Offset |
Size |
Field |
Type |
Notes |
| 0x0A |
1 |
Tx Power Level (dBm) |
SInt8 |
|
| 0x0B |
1 |
Protocol |
UInt8 |
The tag protocol, as used for IR tags. |
| 0x0C |
1 |
Team ID |
UInt8 |
|
| 0x0D |
1 |
Player ID |
UInt8 |
|
| 0x0Eโ0x0F |
2 |
Damage |
SInt16 |
32767 is a one-shot kill. -32767 restores full health. |
| 0x10โ0x13 |
4 |
Color |
Color |
|
| 0x14โ0x19 |
6 |
Target BD_ADDR |
BD_ADDR |
FF:FF:FF:FF:FF:FF targets all devices. |
| 0x1A |
1 |
Splash Target Teams |
UInt8 |
0 = all teams, 1 = the originating team only, 2 = all except the originating team. 0xFF = unspecified (no team filter). |
| 0x1B |
1 |
Splash Minimum RSSI (dBm) |
SInt8 |
Receivers ignore the packet unless its RSSI is greater than this value. 0xFF (-1) means use the receiver's default threshold (-75 dBm in SystemK). |
| 0x1C |
1 |
Hops Remaining |
UInt8 |
How many more times the packet may be relayed, at most 5. 0 or 0xFF means it isn't relayed. |
| 0x1Dโ0x1E |
2 |
Splash ID |
UInt16 |
Identifies one tag across all its relays, so that each device acts on it only once. 0xFFFF means no splash ID (the packet is never relayed). |
Splash Fields
Bytes 0x1A to 0x1E are the splash fields, used by the BLE Bomb and the Bunker Buster (see Accessory Weapons and Splashes). The splash target teams are relative to the Team ID in the packet, which is the team of the originating device.
The originating device sets the splash fields. A device that relays the packet copies everything unchanged except Hops Remaining, which it decrements. This keeps the team filter relative to the originating device, and lets targeted tags still reach their target. A device in any Playing state relays a tag that has hops remaining, whether or not it was the target, and whether or not the tag affected it.
A device that doesn't support splashes sends 0xFF in all five bytes. Receivers treat such a packet as an ordinary, unrelayed tag.
0x04 Console
Carries a text command or message.
| 0/8 | 1/9 | 2/A | 3/B | 4/C | 5/D | 6/E | 7/F |
| 0x00 | Length | Manufacturer Specific Data | Company: Other | KTag Packet Indicator |
| 0x1E | 0xFF | 0xFF | 0xFF | 0x4B โKโ | 0x54 โTโ | 0x61 โaโ | 0x67 โgโ |
| 0x08 | KTag Packet Type | Event Number | Console String |
| 0x04 | 0xXX | | | | | | |
| 0x10 | Console String (cont.) |
| | | | | | | | |
| 0x18 | Console String (cont.) | |
| | | | | | | | |
| Offset |
Size |
Field |
Type |
Notes |
| 0x0Aโ0x1E |
21 |
Console String |
ASCIIZ |
Null-terminated ASCII text, at most 20 characters. Bytes after the terminator are 0x00. |
0x05 Status
Reports a device's current state.
| 0/8 | 1/9 | 2/A | 3/B | 4/C | 5/D | 6/E | 7/F |
| 0x00 | Length | Manufacturer Specific Data | Company: Other | KTag Packet Indicator |
| 0x1E | 0xFF | 0xFF | 0xFF | 0x4B โKโ | 0x54 โTโ | 0x61 โaโ | 0x67 โgโ |
| 0x08 | KTag Packet Type | Event Number | Tx Power Level | Protocol | Team ID | Player ID | Health |
| 0x05 | 0xXX | 0xXX | 0xXX | 0xXX | 0xXX | 0xXX | 0xXX |
| 0x10 | Maximum Health | Primary Color | Secondary Color |
| 0xXX | 0xXX | 0xXX | 0xXX | 0xXX | 0xXX | 0xXX | 0xXX |
| 0x18 | Secondary Color (cont.) | SystemK Top-Level State | Shots Remaining | Shot Capacity | | | |
| 0xXX | 0xXX | 0xXX | 0xXX | 0xXX | 0xFF | 0xFF | |
| Offset |
Size |
Field |
Type |
Notes |
| 0x0A |
1 |
Tx Power Level (dBm) |
SInt8 |
|
| 0x0B |
1 |
Protocol |
UInt8 |
|
| 0x0C |
1 |
Team ID |
UInt8 |
|
| 0x0D |
1 |
Player ID |
UInt8 |
|
| 0x0Eโ0x0F |
2 |
Health |
UInt16 |
|
| 0x10โ0x11 |
2 |
Maximum Health |
UInt16 |
|
| 0x12โ0x15 |
4 |
Primary Color |
Color |
A brightness of 0xFF indicates a False Flag. |
| 0x16โ0x19 |
4 |
Secondary Color |
Color |
A brightness of 0xFF indicates a False Flag. |
| 0x1A |
1 |
SystemK Top-Level State |
UInt8 |
See below. |
| 0x1B |
1 |
Shots Remaining |
UInt8 |
0xFF means not reported. |
| 0x1C |
1 |
Shot Capacity |
UInt8 |
0xFF means not reported. |
| 0x1Dโ0x1E |
2 |
Unused |
|
|
SystemK Top-Level States
| Value |
State |
| 0 |
Initializing |
| 1 |
Reprogramming |
| 2 |
Configuring |
| 3 |
Ready |
| 4 |
Instigating |
| 5 |
Responding |
| 6 |
Counting Down |
| 7 |
Interacting |
| 8 |
Tagged Out |
| 9 |
Consenting |
| 10 |
Wrapping Up |
0x06 Parameters
Reads or changes a device's settings. Each packet carries up to two key/value pairs.
| 0/8 | 1/9 | 2/A | 3/B | 4/C | 5/D | 6/E | 7/F |
| 0x00 | Length | Manufacturer Specific Data | Company: Other | KTag Packet Indicator |
| 0x1E | 0xFF | 0xFF | 0xFF | 0x4B โKโ | 0x54 โTโ | 0x61 โaโ | 0x67 โgโ |
| 0x08 | KTag Packet Type | Event Number | Target BD_ADDR |
| 0x06 | 0xXX | 0xXX | 0xXX | 0xXX | 0xXX | 0xXX | 0xXX |
| 0x10 | Subtype | Parameter Key 1 | Parameter Value 1 | Parameter Key 2 |
| 0xXX | 0xXX | 0xXX | 0xXX | 0xXX | 0xXX | 0xXX | 0xXX |
| 0x18 | Parameter Key 2 (cont.) | Parameter Value 2 | | | |
| 0xXX | 0xXX | 0xXX | 0xXX | 0xXX | 0xFF | 0xFF | |
| Offset |
Size |
Field |
Type |
Notes |
| 0x0Aโ0x0F |
6 |
Target BD_ADDR |
BD_ADDR |
FF:FF:FF:FF:FF:FF targets all devices. |
| 0x10 |
1 |
Subtype |
UInt8 |
See below. |
| 0x11โ0x12 |
2 |
Parameter Key 1 |
UInt16 |
|
| 0x13โ0x16 |
4 |
Parameter Value 1 |
|
Format depends on the key. |
| 0x17โ0x18 |
2 |
Parameter Key 2 |
UInt16 |
|
| 0x19โ0x1C |
4 |
Parameter Value 2 |
|
Format depends on the key. |
| 0x1Dโ0x1E |
2 |
Unused |
|
|
A key of 65535 (0xFFFF) marks an unused key/value pair.
| Subtype |
Meaning |
| 0x00 |
Request Current Parameter Information |
| 0x01 |
Current Parameter Information |
| 0x02 |
Request Parameter Change |
| 0x03 |
Acknowledge Parameter Change |
| 0x04 |
Error Changing Parameters |
| 0x05โ0xFE |
Reserved |
| 0xFF |
Error Responding to Request |
Parameter Keys
| Key |
Meaning |
Value Format |
| 0 |
Reserved |
|
| 1 |
Team ID |
UInt32 |
| 2 |
Player ID |
UInt32 |
| 3 |
Game Length (ms); 0 means untimed |
UInt32 |
| 4 |
Maximum Health |
UInt32 |
| 5 |
Secondary Color |
Color |
| 6 |
Special Weapons Received on Game Reentry |
UInt32 |
| 7 |
Shot Capacity |
UInt32 |
| 8 |
Reload on Game Reentry |
UInt32 (Boolean) |
| 9 |
Minimum Time Between Shots |
UInt32 |
| 10 |
Minimum RSSI to Initiate Transfer (dBm) |
SInt32 |
| 11 |
Accessory Mode: 0 = off, 1 = BLE Bomb, 2 = Bunker Buster |
UInt32 |
| 12 |
Bunker Buster Direct Damage (0 to 255) |
UInt32 |
| 13 |
Splash Damage (0 to 255) |
UInt32 |
| 14 |
Splash Minimum RSSI (dBm, -100 to 0) |
SInt32 |
| 15 |
Splash Target Teams: 0 = all, 1 = originating team only, 2 = all except originating team |
UInt32 |
| 16 |
Special Weapon Cooldown (ms); 0 means no cooldown |
UInt32 |
| 17 |
Splash Hops (0 to 5) |
UInt32 |
| 18โ10000 |
Reserved |
|
| 10001 |
Shots Fired This Game |
UInt32 |
| 10002 |
Tags Received This Game |
UInt32 |
| 10003 |
Times Tagged Out This Game |
UInt32 |
| 10004โ65534 |
Reserved |
|
| 65535 |
Unused Key/Value Pair |
|
0x07 Hello
Announces a device and what it is.
| 0/8 | 1/9 | 2/A | 3/B | 4/C | 5/D | 6/E | 7/F |
| 0x00 | Length | Manufacturer Specific Data | Company: Other | KTag Packet Indicator |
| 0x1E | 0xFF | 0xFF | 0xFF | 0x4B โKโ | 0x54 โTโ | 0x61 โaโ | 0x67 โgโ |
| 0x08 | KTag Packet Type | Event Number | SystemK Major Version | SystemK Minor Version | Device Type | Team ID | Device Name |
| 0x07 | 0xXX | 0xXX | 0xXX | 0xXX | 0xXX | 0xXX | |
| 0x10 | Device Name (cont.) |
| | | | | | | | |
| 0x18 | Device Name (cont.) | |
| | | | | | | | |
| Offset |
Size |
Field |
Type |
Notes |
| 0x0A |
1 |
SystemK Major Version |
UInt8 |
|
| 0x0B |
1 |
SystemK Minor Version |
UInt8 |
|
| 0x0Cโ0x0D |
2 |
Device Type |
UInt16 |
See below. |
| 0x0E |
1 |
Team ID |
UInt8 |
|
| 0x0Fโ0x1E |
16 |
Device Name |
ASCII |
ASCII text, padded with 0x00. A name of exactly 16 characters fills the field and has no terminator. |
The mobile apps use the Device Type to show appropriate icons, among other things.
0x08 Transfer
Moves items, such as K-Points, from one device to another. See the TRANSFER Packet page for how the subtypes work together.
| 0/8 | 1/9 | 2/A | 3/B | 4/C | 5/D | 6/E | 7/F |
| 0x00 | Length | Manufacturer Specific Data | Company: Other | KTag Packet Indicator |
| 0x1E | 0xFF | 0xFF | 0xFF | 0x4B โKโ | 0x54 โTโ | 0x61 โaโ | 0x67 โgโ |
| 0x08 | KTag Packet Type | Event Number | Target BD_ADDR |
| 0x08 | 0xXX | 0xXX | 0xXX | 0xXX | 0xXX | 0xXX | 0xXX |
| 0x10 | Subtype | Team ID | Transaction Number | Item 1 ID | Item 1 Quantity | Item 2 ID |
| 0xXX | 0xXX | 0xXX | 0xXX | 0xXX | 0xXX | 0xXX | 0xXX |
| 0x18 | Item 2 ID (cont.) | Item 2 Quantity | Item 3 ID | Item 3 Quantity | |
| 0xXX | 0xXX | 0xXX | 0xXX | 0xXX | 0xXX | 0xXX | |
| Offset |
Size |
Field |
Type |
Notes |
| 0x0Aโ0x0F |
6 |
Target BD_ADDR |
BD_ADDR |
FF:FF:FF:FF:FF:FF targets all devices. |
| 0x10 |
1 |
Subtype |
UInt8 |
See below. |
| 0x11 |
1 |
Team ID |
UInt8 |
|
| 0x12 |
1 |
Transaction Number |
UInt8 |
See below. |
| 0x13โ0x14 |
2 |
Item 1 ID |
UInt16 |
|
| 0x15โ0x16 |
2 |
Item 1 Quantity |
UInt16 |
65535 means all of the item. |
| 0x17โ0x18 |
2 |
Item 2 ID |
UInt16 |
|
| 0x19โ0x1A |
2 |
Item 2 Quantity |
UInt16 |
65535 means all of the item. |
| 0x1Bโ0x1C |
2 |
Item 3 ID |
UInt16 |
|
| 0x1Dโ0x1E |
2 |
Item 3 Quantity |
UInt16 |
65535 means all of the item. |
The Transaction Number is an arbitrary number that stays the same for the whole transfer. It prevents the same transfer from being made twice.
| Subtype |
Meaning |
| 0x00 |
Reserved |
| 0x01 |
Request Inventory |
| 0x02 |
Inventory (information only; no transfer) |
| 0x03 |
Request Voluntary (needs the player's acknowledgment) |
| 0x04 |
Request Involuntary Friendly (unload) |
| 0x05 |
Request Involuntary Unfriendly (steal) |
| 0x06 |
Offer Unlimited (no two-phase commit needed) |
| 0x07 |
Offer Atomic |
| 0x08 |
Acknowledge Atomic Offer |
| 0x09 |
Commit Atomic Offer |
| 0x0A |
Acknowledge Atomic Commit |
| 0x0B |
Echo BD_ADDR |
| 0x0C |
Acknowledge Echo BD_ADDR |
| 0x0Dโ0xFE |
Reserved |
| 0xFF |
Reserved |
| Item ID |
Item |
| 0x0000 |
Reserved |
| 0x0001 |
K-Point |
| 0x0002โ0xFFFD |
Reserved for future items |
| 0xFFFE |
Transfer nonce (used by Echo BD_ADDR) |
| 0xFFFF |
No item (ignore this ID/quantity pair) |
The transfer nonce isn't a game item. It's a protocol element, and it's never added to or removed from any inventory.