Custom Nettables

Custom Nettables are a powerful new tool to communicate data from the game server to clients. Unlike game events, nettables are persistent stores that can be queried at any time and will be recreated if a player disconnects and reconnects.

Example

Table Registration

You must list top-level table names in game/ADDON_NAME/scripts/custom_net_tables.txt. (If the file doesn't exist in your addon you can create it.) It uses KeyValues3 syntax described here: Dota 2 Workshop Tools/KeyValues3

<!-- kv3 encoding:text:version{e21c7f3c-8a33-41c5-9977-a76d3a32aa0d} format:generic:version{7412167c-06e9-4698-aff2-e63eb59037e7} -->
 {
    custom_net_tables =
    [
        "example_nettable_1",
        "example_nettable_2"
    ]
}

Writing a Nettable on the Server (Lua)

Server code can set table values using this function: CustomNetTables:SetTableValue( string table_name, string key, table value ) A table can have any number of string keys, each of which corresponds to a Lua table value.

Note:When a key's value changes, the ENTIRE value for that key will be networked to each client. (But not other keys in the table.) Values that change frequently should be stored in separate keys to reduce unnecessary network traffic and computation on both client and server.

Note:The maximum amount of data that you can send in a single nettable update is 16384 bytes, otherwise the engine will throw up an error message and crash.

CustomNetTables:SetTableValue( "example_nettable_1", "key_1", {} )
CustomNetTables:SetTableValue( "example_nettable_1", "key_2", { value = "hello" } )
CustomNetTables:SetTableValue( "example_nettable_2", "key_1", { a = 1, b = 2 } )

Reading a Nettable on a Client (Javascript)

When a network table changes on the server, it will be replicated to all clients. Javascript can query the current values in a table, and subscribe to be notified when a table changes.

Note:Latency is an inherent part of any networking system and must be taken into account. For example, if you use a custom game event to send a message from a client to the server, then modify a nettable in response, it may be some time before that client (or any other) sees an updated nettable value.

//--------------------------------------------------------------------------------------------------
// GetAllTableValues returns the entire nettable as a Javascript object
//--------------------------------------------------------------------------------------------------
$.Msg( CustomNetTables.GetAllTableValues( "example_nettable_1" ) );


//--------------------------------------------------------------------------------------------------
// GetTableValue returns the value associated with a particular key
//--------------------------------------------------------------------------------------------------
$.Msg( CustomNetTables.GetTableValue( "example_nettable_2", "key_1" ) );

//--------------------------------------------------------------------------------------------------
// SubscribeNetTableListener allows you to be notified when any value in a table changes
//--------------------------------------------------------------------------------------------------
function OnNettable2Changed( table_name, key, data )
{
	$.Msg( "Table ", table_name, " changed: '", key, "' = ", data );
}

CustomNetTables.SubscribeNetTableListener( "example_nettable_2", OnNettable2Changed );