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:

• grease.Client
• grease.Server
• grease.tcpClient
• grease.udpClient
• grease.enetClient
• grease.tcpServer
• grease.udpServer
• grease.enetServer

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.

• enabled: Whether or not ping messages are used.
• time: How often to send a ping message
• message: What message to send.

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

Connect to a server.

• host: The hostname or ip of the server. (Sadly luasocket is ipv4-only at the time of writing.)
• port: The port at which the server is running.
• dns: Whether to resolve the ‘host’ argument as hostname. (Optional, true by default.)

client:disconnect()

Disconnect from the server, if connected.

client:send(data)

Send data to the server.

• data: A string with data to send.

data = client:receive()

Receive data from the server.

client:update(dt)

Do all time-based stuff, call callbacks etc.

• dt: Delta time, time passed since the last call.

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.

• enabled: Whether or not ping is checked.
• time: When to time out clients (3x the client time seems to work well).
• message: What message clients send.

server:listen(port)

Start listening, allows people to connect.

• port: The port to start listening on.

server:update(dt)

Do all time-based stuff, call callbacks etc.

• dt: Delta time, time passed since the last call.

server:send(data, clientid)

Send data to a/all client(s).

• data: The data to send.
• clientid: The clientid as given by one of the callbacks or receive. Nil/omitted means everyone.

data, clientid = server:receive()

Get data from a (random) client.

• data: The data sent by the client.
• clientid: The id associated to the client (see the Client IDs section).

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.