goworld

README

GoWorld

Scalable Distributed Game Server Engine with Hot Reload in Golang

---

• Features
• Architecture
• Introduction
• Get GoWorld
• Manage GoWorld using goworld.py
• Demos
  • Chatroom Demo
  • Unity Demo

---

中文资料： 游戏服务器介绍 目录结构说明 使用GoWorld轻松实现分布式聊天服务器 欢迎加入Go服务端开发交流群：662182346

---

Features

• Spaces & Entities: manage multiple spaces and entities with AOI support
• Distributed: increase server capacity by using more machines
• Hot-Swappable: update game logic by restarting server process
• Multiple Communication Protocols: supports TCP, KCP and WebSocket
• Traffic Compression & Encryption: traffic between clients and servers can be compressed and encrypted

Architecture

Introduction

GoWorld server adopts an entity framework, in which entities represent all players, monsters, NPCs. Entities in the same space can visit each other directly by calling methods or access attributes. Entities in different spaces can call each over using RPC.

A GoWorld server consists of one dispatcher, one or more games and one or more gates. The gates are responsible for handling client connections and receive/send packets from/to clients. The games manages all entities and runs all game logic. The dispatcher is responsible for redirecting packets among games and between games and gates.

The game processes are hot-swappable. We can swap a game by sending SIGUSR1 to the process and restart the process with -restore parameter to bring game back to work but with the latest executable image. This feature enables updating server-side logic or fixing server bugs transparently without significant interference of online players.

Get GoWorld

$ go get github.com/xiaonanln/goworld

Install dependencies

GoWorld uses Glide to manage packages.

Windows:

1. get glide.exe from https://github.com/Masterminds/glide/releases and put it to $GOPATH/bin
2. run install-deps-win.bat

Linux:

1. Install Glide: $ curl https://glide.sh/get | sh
2. $ make install-deps

For Chinese only: 中国的朋友可能会碰到网络问题，那么您可以通过点击下载vendor.zip，并将其解压到goworld根目录下。 不过vendor.zip里的内容有可能不是最新的。

Manage GoWorld using goworld.py

goworld.py is a script for managing goworld server easily. Running goworld.py requires python 2.7.x and psutil module. We can use goworld.py to build, start, stop and reload game servers.

$ pip install psutil

Build Dispatcher & Gate:

$ python goworld.py build dispatcher gate

Build Example Chatroom Server:

$ python goworld.py build examples/chatroom_demo

Start Example Chatroom Server: (dispatcher -> game -> gate)

$ python goworld.py start examples/chatroom_demo

Stop Game Server (gate -> game -> dispatcher):

$ python goworld.py stop

Reload Game Servers:

$ python goworld.py reload

Reload will reboot game processes with the current executable while preserving all game server states. However, it is not workable on Windows.

Demos

Chatroom Demo

The chatroom demo is a simple implementation of chatroom server and client. It illustrates how GoWorld can also be used for games which don't divide players by spaces.

The chatroom demo provides following features:

• register & login
• send chat message
• switch chatrooms

Build Server:

$ python goworld.py build dispatcher gate chatroom_demo

Run Server:

$ python goworld.py start chatroom_demo

Chatroom Demo Client:

Chatroom demo client implements the client-server protocol in Javascript.
The client for chatroom demo is hosted at github.com/xiaonanln/goworld-chatroom-demo-client. The project was created and built in Cocos Creater 1.5. A running server and client demo can also be found at http://goworldgs.com/chatclient/.

Unity Demo

Unity Demo is a simple multiple player monster shooting game to show how spaces and entities of GoWorld can be used to create multiple player online games.

• register & login
• move players in space
• summon monsters
• player shoot monsters
• monsters attack players

Developing features:

• Hit effects
• Players migrate among multiple spaces
• Server side map navigation

Build Server:

$ python goworld.py build dispatcher gate unity_demo

Run Server:

$ python goworld.py start unity_demo

Unity Demo Client:

Unity demo client implements the client-server protocol in C#. The client for unity demo is hosted at https://github.com/xiaonanln/goworld-unity-demo. The project was created and built in Unity 2017.1.

Documentation

Index

• func CreateEntityAnywhere(typeName string)
• func CreateEntityLocally(typeName string) common.EntityID
• func CreateSpaceAnywhere(kind int)
• func CreateSpaceLocally(kind int) common.EntityID
• func Entities() entity.EntityMap
• func Exists(typeName string, entityID common.EntityID, callback storage.ExistsCallbackFunc)
• func GetEntity(id common.EntityID) *entity.Entity
• func GetGameID() uint16
• func GetKVDB(key string, callback kvdb.KVDBGetCallback)
• func GetOrPutKVDB(key string, val string, callback kvdb.KVDBGetOrPutCallback)
• func GetServiceProviders(serviceName string) entity.EntityIDSet
• func ListAttr() *entity.ListAttr
• func ListEntityIDs(typeName string, callback storage.ListCallbackFunc)
• func LoadEntityAnywhere(typeName string, entityID common.EntityID)
• func MapAttr() *entity.MapAttr
• func Post(callback post.PostCallback)
• func PutKVDB(key string, val string, callback kvdb.KVDBPutCallback)
• func RegisterEntity(typeName string, entityPtr interface{}, isPersistent, useAOI bool) *entity.EntityTypeDesc
• func RegisterSpace(spacePtr interface{})
• func Run(delegate game.IGameDelegate)

Functions

func CreateEntityAnywhere

func CreateEntityAnywhere(typeName string)

CreateEntityAnywhere creates a entity on any server

func CreateEntityLocally

func CreateEntityLocally(typeName string) common.EntityID

CreateEntityLocally creates a entity on the local server

returns EntityID

func CreateSpaceAnywhere

func CreateSpaceAnywhere(kind int)

CreateSpaceAnywhere creates a space with specified kind in any game server

func CreateSpaceLocally

func CreateSpaceLocally(kind int) common.EntityID

CreateSpaceLocally creates a space with specified kind in the local game server

returns the space EntityID

func Entities

func Entities() entity.EntityMap

Entities gets all entities as an EntityMap (do not modify it!)

func Exists

func Exists(typeName string, entityID common.EntityID, callback storage.ExistsCallbackFunc)

Exists checks if entityID exists in entity storage

returns result in callback

func GetEntity

func GetEntity(id common.EntityID) *entity.Entity

GetEntity gets the entity by EntityID

func GetGameID

func GetGameID() uint16

GetGameID gets the local server ID

server ID is a uint16 number starts from 1, which should be different for each servers server ID is also in the game config section name of goworld.ini

func GetKVDB

func GetKVDB(key string, callback kvdb.KVDBGetCallback)

GetKVDB gets value of key from KVDB

func GetOrPutKVDB

func GetOrPutKVDB(key string, val string, callback kvdb.KVDBGetOrPutCallback)

GetOrPut gets value of key from KVDB, if val not exists or is "", put key-value to KVDB.

func GetServiceProviders

func GetServiceProviders(serviceName string) entity.EntityIDSet

GetServiceProviders get the set of EntityIDs that provides the specified service

func ListAttr

func ListAttr() *entity.ListAttr

ListAttr creates a new ListAttr

func ListEntityIDs

func ListEntityIDs(typeName string, callback storage.ListCallbackFunc)

ListEntityIDs gets all saved entity ids in storage, may take long time and block the main routine

returns result in callback

func LoadEntityAnywhere

func LoadEntityAnywhere(typeName string, entityID common.EntityID)

LoadEntityAnywhere loads the specified entity from entity storage

func MapAttr

func MapAttr() *entity.MapAttr

MapAttr creates a new MapAttr

func Post

func Post(callback post.PostCallback)

Post posts a callback to be executed

func PutKVDB

func PutKVDB(key string, val string, callback kvdb.KVDBPutCallback)

PutKVDB puts key-value to KVDB

func RegisterEntity

func RegisterEntity(typeName string, entityPtr interface{}, isPersistent, useAOI bool) *entity.EntityTypeDesc

RegisterEntity registers the entity type so that entities can be created or loaded

returns the entity type description object which can be used to define more properties of entity type

func RegisterSpace

func RegisterSpace(spacePtr interface{})

RegisterSpace registers the space entity type.

All spaces will be created as an instance of this type

func Run

func Run(delegate game.IGameDelegate)

Run runs the server endless loop

This is the main routine for the server and all entity logic, and this function never quit