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/versions

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!

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.

License

The BSD 3-Clause License (BSD-3-Clause) 2019 - Yannick Deubel. Please have a look at the LICENSE for more details.