|
@@ -3,8 +3,8 @@
|
|
**lua-enet** is a binding to the [ENet](http://enet.bespin.org/) library for
|
|
**lua-enet** is a binding to the [ENet](http://enet.bespin.org/) library for
|
|
Lua. ENet is a thin network communication layer over UDP that provides high
|
|
Lua. ENet is a thin network communication layer over UDP that provides high
|
|
performance and reliable communication that is suitable for games. The
|
|
performance and reliable communication that is suitable for games. The
|
|
-interface exposes an asynchronous non-blocking way of creating clients and
|
|
|
|
-servers that is easy to integrate into existing event loops.
|
|
|
|
|
|
+interface exposes an asynchronous way of creating clients and servers that is
|
|
|
|
+easy to integrate into existing event loops.
|
|
|
|
|
|
To get an idea of how ENet works and what it provides have a look at
|
|
To get an idea of how ENet works and what it provides have a look at
|
|
[Features and Achritecture](http://enet.bespin.org/Features.html) from the
|
|
[Features and Achritecture](http://enet.bespin.org/Features.html) from the
|
|
@@ -16,16 +16,14 @@ original documentation.
|
|
* [License](#license)
|
|
* [License](#license)
|
|
* [Contact](#contact)
|
|
* [Contact](#contact)
|
|
|
|
|
|
-
|
|
|
|
<a name="install"></a>
|
|
<a name="install"></a>
|
|
## Download & Install
|
|
## Download & Install
|
|
The easiest way to install **lua-enet** is to use [Lua Rocks](http://www.luarocks.org/):
|
|
The easiest way to install **lua-enet** is to use [Lua Rocks](http://www.luarocks.org/):
|
|
|
|
|
|
$ luarocks install enet
|
|
$ luarocks install enet
|
|
|
|
|
|
-The source can be obtained from github:
|
|
|
|
-<http://leafo.net/github/lua-enet>
|
|
|
|
-
|
|
|
|
|
|
+The source can be obtained from GitHub:
|
|
|
|
+<https://github.com/leafo/lua-enet>
|
|
|
|
|
|
<a name="tutorial"></a>
|
|
<a name="tutorial"></a>
|
|
## Tutorial
|
|
## Tutorial
|
|
@@ -54,8 +52,8 @@ Using this information, we can make a simple echo server:
|
|
end
|
|
end
|
|
|
|
|
|
|
|
|
|
-Data, whether sent or received is always a Lua string. Primitive types can be
|
|
|
|
-converted to a binary string to reduce the number of bytes used using a binary
|
|
|
|
|
|
+Data, whether sent or received, is always a Lua string. Primitive types can be
|
|
|
|
+converted to a binary string to reduce the number of bytes sent by using a binary
|
|
serialization library.
|
|
serialization library.
|
|
|
|
|
|
The client for our server can be written like so:
|
|
The client for our server can be written like so:
|
|
@@ -86,21 +84,20 @@ Upon receiving the connect message we send `"hello world"` to the server, then
|
|
wait for the response.
|
|
wait for the response.
|
|
|
|
|
|
When a client disconnects, make sure to call `disconnect` on the server object,
|
|
When a client disconnects, make sure to call `disconnect` on the server object,
|
|
-and then tell the host to flush (unless `host_service` will be called again)
|
|
|
|
|
|
+and then tell the host to flush (unless `host:service` will be called again)
|
|
otherwise the server will have to wait for the client to disconnect from timeout.
|
|
otherwise the server will have to wait for the client to disconnect from timeout.
|
|
|
|
|
|
<a name="reference"></a>
|
|
<a name="reference"></a>
|
|
## Reference
|
|
## Reference
|
|
|
|
|
|
-
|
|
|
|
### `enet.host_create([bind_address, peer_count, channel_count, in_bandwidth, out_bandwidth])`
|
|
### `enet.host_create([bind_address, peer_count, channel_count, in_bandwidth, out_bandwidth])`
|
|
Returns a new host. All arguments are optional.
|
|
Returns a new host. All arguments are optional.
|
|
|
|
|
|
A `bind_address` of `nil` makes a host that can not be connected to (typically
|
|
A `bind_address` of `nil` makes a host that can not be connected to (typically
|
|
-a client). Otherwise the address can either be of the form
|
|
|
|
|
|
+a client). Otherwise the address can either be of the form
|
|
`<ipaddress>:<port>`, `<hostname>:<port>`, or `*:<port>`.
|
|
`<ipaddress>:<port>`, `<hostname>:<port>`, or `*:<port>`.
|
|
|
|
|
|
-Examples addresses include `"127.0.0.1:8888"`, `"localhost:2232"`, and `"*:6767"`.
|
|
|
|
|
|
+Example addresses include `"127.0.0.1:8888"`, `"localhost:2232"`, and `"*:6767"`.
|
|
|
|
|
|
Parameters:
|
|
Parameters:
|
|
|
|
|
|
@@ -111,10 +108,10 @@ Parameters:
|
|
* `out_bandwidth` upstream bandwidth in bytes/sec, defaults to `0`
|
|
* `out_bandwidth` upstream bandwidth in bytes/sec, defaults to `0`
|
|
(unlimited)
|
|
(unlimited)
|
|
|
|
|
|
-### `host:connect(address [, channels_count, data])`
|
|
|
|
-Connects a host to a remote host. Returns peer object associated with remote host.
|
|
|
|
-The actual connection will not take place until the next `host:service` done,
|
|
|
|
-in which a `"connect"` event will be generated.
|
|
|
|
|
|
+### `host:connect(address [, channel_count, data])`
|
|
|
|
+Connects a host to a remote host. Returns peer object associated with remote
|
|
|
|
+host. The actual connection will not take place until the next `host:service`
|
|
|
|
+is done, in which a `"connect"` event will be generated.
|
|
|
|
|
|
`channel_count` is the number of channels to allocate. It should be the same as
|
|
`channel_count` is the number of channels to allocate. It should be the same as
|
|
the channel count on the server. Defaults to `1`.
|
|
the channel count on the server. Defaults to `1`.
|
|
@@ -124,14 +121,14 @@ Defaults to `0`.
|
|
|
|
|
|
### `host:service([timeout])`
|
|
### `host:service([timeout])`
|
|
Wait for events, send and receive any ready packets. `timeout` is the max
|
|
Wait for events, send and receive any ready packets. `timeout` is the max
|
|
-number of milliseconds to be wait for an event. By default `timeout` is `0`.
|
|
|
|
-Returns `nil` on timeout if not events occurred.
|
|
|
|
|
|
+number of milliseconds to be waited for an event. By default `timeout` is `0`.
|
|
|
|
+Returns `nil` on timeout if no events occurred.
|
|
|
|
|
|
-If an event happens an event table is returned. All events have a `type` entry,
|
|
|
|
-which is one of `"connect"`, `"disconnect"`, `"receive"`. Events also have a
|
|
|
|
|
|
+If an event happens, an event table is returned. All events have a `type` entry,
|
|
|
|
+which is one of `"connect"`, `"disconnect"`, or `"receive"`. Events also have a
|
|
`peer` entry which holds the peer object of who triggered the event.
|
|
`peer` entry which holds the peer object of who triggered the event.
|
|
|
|
|
|
-A receive event also has a `data` entry which is a Lua string containing the
|
|
|
|
|
|
+A `"receive"` event also has a `data` entry which is a Lua string containing the
|
|
data received.
|
|
data received.
|
|
|
|
|
|
### `host:check_events()`
|
|
### `host:check_events()`
|
|
@@ -150,7 +147,7 @@ maximum allowable value is used.
|
|
Sets the bandwidth limits of the host in bytes/sec. Set to `0` for unlimited.
|
|
Sets the bandwidth limits of the host in bytes/sec. Set to `0` for unlimited.
|
|
|
|
|
|
### `peer:send(data [, channel, flag])`
|
|
### `peer:send(data [, channel, flag])`
|
|
-Queues a packet to be sent to dir. `data` is the contents of the packet, it
|
|
|
|
|
|
+Queues a packet to be sent to peer. `data` is the contents of the packet, it
|
|
must be a Lua string.
|
|
must be a Lua string.
|
|
|
|
|
|
`channel` is the channel to send the packet on. Defaults to `0`.
|
|
`channel` is the channel to send the packet on. Defaults to `0`.
|
|
@@ -161,7 +158,7 @@ Unsequenced packets are unreliable and have no guarantee on the order they
|
|
arrive. Defaults to reliable.
|
|
arrive. Defaults to reliable.
|
|
|
|
|
|
### `peer:disconnect([data])`
|
|
### `peer:disconnect([data])`
|
|
-Requests a disconnection from the peer. The message is sent on next
|
|
|
|
|
|
+Requests a disconnection from the peer. The message is sent on the next
|
|
`host:service` or `host:flush`.
|
|
`host:service` or `host:flush`.
|
|
|
|
|
|
`data` is optional integer value to be associated with the disconnect.
|
|
`data` is optional integer value to be associated with the disconnect.
|
|
@@ -185,7 +182,7 @@ Forcefully disconnects peer. The peer is not notified of the disconnection.
|
|
Send a ping request to peer, updates `round_trip_time`. This is called
|
|
Send a ping request to peer, updates `round_trip_time`. This is called
|
|
automatically at regular intervals.
|
|
automatically at regular intervals.
|
|
|
|
|
|
-### `peer:throttle_configure(interval, acceleration, decceleration)`
|
|
|
|
|
|
+### `peer:throttle_configure(interval, acceleration, deceleration)`
|
|
Changes the probability at which unreliable packets should not be dropped.
|
|
Changes the probability at which unreliable packets should not be dropped.
|
|
|
|
|
|
Parameters:
|
|
Parameters:
|
|
@@ -193,7 +190,7 @@ Parameters:
|
|
* `interval` interval in milliseconds to measure lowest mean RTT
|
|
* `interval` interval in milliseconds to measure lowest mean RTT
|
|
* `acceleration` rate at which to increase throttle probability as mean RTT
|
|
* `acceleration` rate at which to increase throttle probability as mean RTT
|
|
declines
|
|
declines
|
|
- * `decceleration` rate at which to decrease throttle probability as mean RTT
|
|
|
|
|
|
+ * `deceleration` rate at which to decrease throttle probability as mean RTT
|
|
increases
|
|
increases
|
|
|
|
|
|
### `peer:receive()`
|
|
### `peer:receive()`
|