Snapshot

This file is mirrored from the libtw2 documentation and is dual-licensed under MIT or APACHE.

Introduction

Teeworlds uses this format of so called "snapshots" to transmit the current state of the world over the network. The format allows one to transmit fixed-size "items".

Terminology

All integers in this document are little-endian integers.

Item key

An item key is a 32-bit unsigned integer that contains the 16-bit unsigned integer type_id as the upper bits and id as the lower bits.

Items

An item consists of an item key key and an array of 32-bit signed integers data.

Snapshot

A snapshot is a collection of items identified by their key.

Format

Checksum calculation

The checksum of a snapshot is calculated by summing all the data array elements of all items, using wrapping overflow behavior.

Snapshot deltas

snapshot_delta:
    [ 4] num_removed_items
    [ 4] num_item_deltas
    [ 4] _zero
    [*4] removed_item_keys
    [  ] item_deltas

Snapshot deltas are used to describe the differences between two snapshots, the "old" and the "new" one. You can use the delta together with the old snapshot to construct the new one. Note that the reverse does not work, because the values of snapshot items present in the old but not the new snapshot are not recorded in the delta.

• num_removed_items is a positive signed 32-bit integer describing the length of the removed_item_keys array.
• num_item_deltas is a positive signed 32-bit integer describing the number of item deltas in the item_deltas field.
• _zero is a padding field which must be zeroed by any snapshot delta writer and ignored by any snapshot delta reader.
• removed_item_keys is an array of num_removed_items item keys that are present in old snapshot, but not in the new one.
• item_deltas is a concatenation of num_item_deltas item deltas.

Item deltas

item_delta:
    [ 4] type_id
    [ 4] id
    [ 4] _size
    [*4] data_delta

• type_id is a 32-bit unsigned integer containing the 16-bit type id of the item.
• id is 32-bit unsigned integer containing the 16-bit id of the item.
• _size is a field that is only present if the size of items of type type_id is not pre-agreed for the protocol. A list of pre-agreed item sizes can be found in the appendix of this document.
• data_delta is the data delta (an array of _size 32-bit signed integers). If the item was not present in the old snapshot (determined by the item key), then data_delta just contains the new item data. Otherwise, the data_delta needs to be added onto the current item's data (elementwise) using 32-bit integer addition that wraps around on overflow. Note that in the case of item update, the new size must be the same as the old size of the item data.

Appendix

Pre-agreed item sizes

The following describes the 0.6 protocol of Teeworlds.

type_id	size	name
1	10	obj_player_input
2	6	obj_projectile
3	5	obj_laser
4	4	obj_pickup
5	3	obj_flag
6	8	obj_game_info
7	4	obj_game_data
8	15	obj_character_core
9	22	obj_character
10	5	obj_player_info
11	17	obj_client_info
12	3	obj_spectator_info
13	2	event_common
14	2	event_explosion
15	2	event_spawn
16	2	event_hammerhit
17	3	event_death
18	3	event_sound_global
19	3	event_sound_world
20	3	event_damage_indicator

The following describes the 0.7 protocol of Teeworlds. There were more items added after the initial 0.7 release, but they're not "pre-agreed item sizes" to stay backward compatible.

type_id	size	name
1	10	obj_player_input
2	6	obj_projectile
3	5	obj_laser
4	3	obj_pickup
5	3	obj_flag
6	3	obj_game_data
7	2	obj_game_data_team
8	4	obj_game_data_flag
9	15	obj_character_core
10	22	obj_character
11	3	obj_player_info
12	4	obj_spectator_info
13	58	obj_client_info
14	5	obj_game_info
15	32	obj_tune_params
16	2	event_common
17	2	event_explosion
18	2	event_spawn
19	2	event_hammerhit
20	3	event_death
21	3	event_sound_world
22	5	event_damage