Attention

Pitaya is currently under development and is not yet ready for production use. We're working on tests and better documentation and we'll update the project as soon as possible.

pitaya

Pitaya is an easy to use, fast and lightweight game server framework inspired by starx and pomelo and built on top of nano's networking library.

The goal of pitaya is to provide a basic development framework for distributed multiplayer games and server-side applications.

How to build a system with pitaya

What does a pitaya application look like?

A pitaya application is a collection of components made of handlers and/or remotes.

Handlers are methods that will be called directly by the client while remotes are called by other servers via RPCs. Once you register a component to pitaya, pitaya will register to its service container all methods that can be converted to Handler or Remote.

Handlers

Pitaya service handler will be called when the client makes a request and it receives one or two parameters while handling a message:

• context.Context: the context of the request, which contains the client's session.
• pointer or []byte: the payload of the request (optional).

There are two types of handlers, request and push. For the first case the handler must have two return values:

• pointer or []byte: the response payload
• error: an error variable

for the second type the method should not return anything.

Remotes

Pitaya service remote will be called by other pitaya servers and it receives one or two parameters while handling the request:

• context.Context: the context of the request.
• protobuf: the payload in protobuf format (optional).

The remote method should always return two parameters:

• protobuf: the response payload in protobuf format.
• error: an error variable

Standalone application

The easiest way of running pitaya is by starting a standalone application. There's an working example here.

Cluster mode

In order to run several pitaya applications in a cluster it is necessary to configure RPC and Service Discovery services. Currently we are using NATS for RPC and ETCD for service discovery as default options. The option to use gRPC for RPC is also available. Other options may be implemented in the future.

There's an working example of pitaya running in cluster mode here.

To run this example you need to have both nats and etcd running. To start them you can use the following commands:

docker run -p 4222:4222 -d --name nats-main nats
docker run -d -p 2379:2379 -p 2380:2380 appcelerator/etcd

You can start the backend and frontend servers with the following commands:

make run-cluster-example-frontend
make run-cluster-example-backend

Frontend and backend servers

In short, frontend servers handle client calls while backend servers only handle RPCs coming from other servers. Both types of servers are capable of receiving RPCs.

Frontend servers are responsible for accepting connections with the clients and processing the messages, forwarding them to the appropriate servers as needed. Backend servers receive messages forwarded from the frontend servers. It's possible to set custom forwarding logic based on the client's session data, route and payload.

Resources

• Documents

  • API Reference
  • In-depth documentation

• Demo

  • Implement a chat room in ~100 lines with pitaya and WebSocket (adapted from nano's example)
  • Tadpole demo (adapted from nano's example)
  • Pitaya cluster mode example
  • Pitaya cluster mode with protobuf compression example

Installation

go get github.com/topfreegames/pitaya

# dependencies
make setup

Testing

make test

Benchmark

TBD

License

MIT License

Forked from © 2017 nano Authors