Grease

Grease is a networking library for lua, using LuaSocket, and optionally Lua-ENet. It was designed to operate within the LÖVE framework, but also works without it.

Grease has been built with classes in mind, and for that purpose it uses Class Commons, a compatibility layer between lua class libraries. To help people who are not interested in it, it also comes with a minimal implementation as a fallback.

Types

Grease comes with several base types, and their implementations. These are:

Note that you should probably not be using either of the base classes (grease.Client or grease.Server), nor deriving from them, unless you want to implement a new low-level protocol (and you don’t.) You should also probably not be deriving from any of the other classes, instead just instantiating them.

grease.Client

client:setPing(enabled, time, message)

Sets the ping settings for this client.

success, error = client:connect(host, port, dns)

Connect to a server.

client:disconnect()

Disconnect from the server, if connected.

client:send(data)

Send data to the server.

data = client:receive()

Receive data from the server.

client:update(dt)

Do all time-based stuff, call callbacks etc.

client:setOption(option, value)

WARNING: Due to a bug, this function is called setoption for tcp and enet. Set an option for this socket. * option: One of:

  * "broadcast": Allow connectivity with broadcast addresses, may fail.

client.handshake

Used in connect/disconnect messages, should match the server’s.
WARNING: The handshake shouldn’t occur in normal (other) messages.

client.callbacks.recv(data)

Called whenever a client receives data, and is subsequently updated, meant to be overridden by user.

grease.Server

server:setPing(enabled, time, message)

Sets the ping settings used on this server.

server:listen(port)

Start listening, allows people to connect.

server:update(dt)

Do all time-based stuff, call callbacks etc.

server:send(data, clientid)

Send data to a/all client(s).

data, clientid = server:receive()

Get data from a (random) client.

server.handshake

Used in connect/disconnect messages, should match the client’s.
WARNING: The handshake shouldn’t occur in normal (other) messages.

server.callbacks.recv(data, clientid)

Called whenever a server receives data, and is subsequently updated, meant to be overridden by user.

server.callbacks.connect(clientid)

Called whenever a client connects to the server, and is subsequently updated, meant to be overridden by user.

server.callbacks.disconnect(clientid)

Called whenever a client disconnects from the server, and is subsequently updated, meant to be overridden by user.

Client IDs

Client IDs are used to identify specific clients connected to a server, they are completely implementation-defined and you should only use obtained Client IDs either as unique indexes for your storage (but take care to not prevent garbage collection), or as input for Grease’s functions. Any Client IDs given to Grease must also have been obtained from it.