
geckos.io
Geckos.io offers real-time client/server communication over UDP using WebRTC and Node.js
Geckos.io fits perfectly with your next HTML5 real-time multiplayer games or chat app.
What is it made for?
It's designed specifically for your HTML5 real-time multiplayer games by lowering the average latency and preventing huge latency spikes.
Getting Started
First things first, install it via npm:
npm install @geckos.io/client @geckos.io/server
Usage
client.js
import geckos from '@geckos.io/client'
// or add a minified version to your index.html file
// https://github.com/geckosio/geckos.io/tree/master/bundles
const channel = geckos()
channel.onConnect(error => {
if (error) {
console.error(error.message)
return
}
channel.on('chat message', data => {
console.log(`You got the message ${data}`)
})
channel.emit('chat message', 'a short message sent to the server')
})
server.js
const geckos = require('@geckos.io/server').default
// or with es6
import geckos from '@geckos.io/server'
const io = geckos()
io.listen()
io.onConnection(channel => {
channel.onDisconnect(() => {
console.log(`${channel.id} got disconnected`)
})
channel.on('chat message', data => {
console.log(`got ${data} from "chat message"`)
// emit the "chat message" data to all channels in the same room
io.room(channel.roomId).emit('chat message', data)
})
})
Cheatsheet
You will find all the available methos in the cheatsheet!
Reliable Messages (experimental in v1.3.0-alpha.0)
All emit function can send reliable message if needed. This is NOT meant to be used as the default. Just use it to send important messages back and forth.
It works by simply transferring multiple messages after each other. The receiver will simply reject a message if it has already been processed.
channel.emit('end of game', {
points: 147,
time: 650,
achievements: ['crucial_hit','golden_trophy']
}, {
// Set the reliable option
// Default: false
reliable: true,
// The interval between each message in ms (optional)
// Default: 150
interval: 150,
// How many times the message should be sent (optional)
// Default: 10
runs: 10
})
Servers
Standalone
import geckos from '@geckos.io/server'
const io = geckos()
io.onConnection( channel => { ... })
io.listen()
Node.js HTTP Server
const geckos = require('@geckos.io/server').default
const http = require('http')
const server = http.createServer()
const io = geckos()
io.addServer(server)
io.onConnection( channel => { ... })
server.listen(3000)
Express
const geckos = require('@geckos.io/server').default
const http = require('http')
const express = require('express')
const app = express()
const server = http.createServer(app)
const io = geckos()
io.addServer(server)
io.onConnection( channel => { ... })
server.listen(3000)
Deployment
You have to make sure you deploy it to a server which forwards all traffic on ports 9208/tcp and 0-65535/upd to your application.
Port 9208/tcp is used for the peer signaling. The peer connection itself will be on a random port between 0-65535/upd.
ICE Servers
Geckos.io provides a default list of ICE servers for testing. In production, you should probably use your own STUN and TURN servers.
const geckos = require('@geckos.io/server').default
const { iceServers } = require('@geckos.io/server')
// or
import geckos, { iceServers } from '@geckos.io/server'
// use an empty array if you are developing locally
// use the default iceServers if you are testing it on your server
const io = geckos({ iceServers: null, TESTING_LOCALLY ? [] : iceServers })
Watch a useful video about ICE Servers on YouTube.
TypeScript
Geckos.io is written in TypeScript. If you import geckos.io with the import
statement, the types will be imported as well.
// client.js
import geckos, { Data } from '@geckos.io/client'
const channel = geckos({ url: 'YOUR_SERVER_URL' })
channel.onConnect(() => {
channel.on('chat message', (data: Data) => {
// ...
})
})
// server.js
import geckos, { Data, Channel } from '@geckos.io/server'
const io = geckos()
io.onConnection((channel: Channel) => {
channel.on('chat message', (data: Data) => {
// ...
})
})
Examples
socket.io vs geckos.io vs peerjs
TODO: Note some differences here.
When to use socket.io, geckos.io or peerjs?
socket.io | geckos.io | peerjs | |
---|---|---|---|
Real-Time Multiplayer Game (with authoritative server) |
● | ||
Real-Time Multiplayer Game (without authoritative server) |
● | ||
Turn based Multiplayer Game (with authoritative server) |
● | ||
Turn based Multiplayer Game (without authoritative server) |
● | ● | |
Chat App | ● | ● | |
Any other App with Real-Time communication | ● | ● | ● |
Development
To help developing geckos.io, install this repository via npm install
. Test it with npm test
. Then start the development server with npm run dev
.
Automated Tests
We do run automated tests for Node.js 8, 10, 11 and 12 using Docker on Jenkins on localhost with the Dockerfiles in ./dockerfiles using this Jenkins setup.
License
The BSD 3-Clause License (BSD-3-Clause) 2019 - Yannick Deubel. Please have a look at the LICENSE for more details.