Grease

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, defaults to true.

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)

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

  • 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. Their values are implementation-defined, but can be used to uniquely identify clients. Any Client IDs given to Grease must also have been obtained from it.