cable object
Object table cable in lib/cable.lua
Cable is a thin wrapper around the net library that sends any number of values in one call.
Cable.send writes its arguments one after another, serializing tables with SFS, and
Cable.receive sets the handler that gets them back as regular arguments, so that there is
no reading or writing of individual net types. A nil argument arrives as nil and does not
cut off the arguments after it. Message names become networked strings the first time
the server uses them.
A net message holds 64 KB at most. Values that do not fit are sent in chunks: the whole
argument list is serialized with SFS as one block, compressed, cut into pieces of
Cable.chunk_size bytes and sent one piece every Cable.chunk_interval seconds under the
fl_cable_chunk name. The other side puts the pieces back together and runs the handler
as if the message had arrived in one piece, so a table of any size goes through a single
Cable.send call. Values that SFS cannot serialize, such as functions, cannot be chunked.
The server accepts chunked messages from a client only for names that have a handler, up
to Cable.max_transfer_size bytes and Cable.max_transfers_per_player at a time, and
forgets a transfer that has not completed within Cable.transfer_timeout seconds.
-- Any size, on either side:
Cable.send(target, 'fl_map_data', huge_table)
Cable.receive('fl_map_data', function(data)
print(table.Count(data))
end)
Both realms run this file; the package installer sends it to clients.
Summary
Functions
Cable.receive.Functions
Makes sure that a message name is a networked string, adding it if necessary. Serverside only.
Parameters
- id String message name
Returns
- Boolean true if the name was already known, false if it has just been added
Checks whether a message has a handler set with Cable.receive.
Parameters
- id String message name
Returns
- Boolean
Counts the chunked transfers that are still waiting for pieces on this side.
Returns
- Number
Sets the function that handles an incoming Cable message, however it arrives. On the server the callback receives the sending player followed by the sent values, on the client it receives the sent values only.
-- Server:
Cable.receive('fl_config_change', function(actor, key, value)
if !actor:can('manage_configuration') then return end
Config.set(key, value)
end)
-- Client:
Cable.receive('fl_config_set_var', function(key, value)
print(key, value)
end)
Parameters
- id String message name
- callback Function message handler
On the server
Sends a Cable message to one, several or all players. Serverside variant.
Tables are serialized with SFS, and nil values are delivered as nil. Messages under a new
name are delayed until 0.1 seconds after the first one, to let the networked string reach
the clients, and are then sent in the order they were queued in.
Values that do not fit into one net message are sent in chunks (see the top of this
file), which takes Cable.chunk_interval seconds per piece after the first.
Cable.send(target, 'fl_bind_pressed', key)
Cable.send(nil, 'fl_player_disconnected', actor:EntIndex()) -- to everyone
A player who is not valid any more, such as one who has left, is nobody: a single invalid player gets no message and invalid players are left out of a list. A list without a valid player sends nothing. Only nil stands for everyone.
Parameters
- target Player/List<Player> who to send the message to; everyone if nil
- id String message name
- ... Vararg values to send
On the client
Sends a Cable message to the server. Clientside variant. Tables are serialized with SFS, and nil values are delivered as nil. Values that do not fit into one net message are sent in chunks (see the top of this file), which the server only accepts for a message that has a handler there.
Cable.send('fl_config_change', key, value)
Parameters
- id String message name
- ... Vararg values to send
Defined in
- lib/cable.lua:471 server
- lib/cable.lua:539 client