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

• Multiplayer Game with phaser.io
• Simple Chat App Example

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.