goworld: github.com/xiaonanln/goworld Index | Files | Directories

package goworld

import "github.com/xiaonanln/goworld"

GoWorld is a distributed game server engine. GoWorld adopts a Space-Entity framework for game server programming. Entities can migrate between spaces by calling `EnterSpace`. Entities can call each other using EntityID which is a global unique identifier for each entity. Entites can be used to represent game objects like players, monsters, NPCs, etc.


GoWorld server contains multiple processes. There should be at least 3 processes: 1 dispatcher + 1 gate + 1 game. The gate process is responsable for handling game client connections. Currently, gate supports multiple transmission protocol including TCP, KCP or WebSocket. It also support data compression and encryption. The game process is where game logic actually runs. A Space will always reside in one game process where it is created. Entities can migrate between multiple game processes by entering spaces on other game processes. GoWorld server can scale arbitrarily by running more process.

Package goworld

goworld package is dedicated to provide GoWorld game engine APIs for developers. Most of time developers should use functions exported by goworld package to manipulate spaces and entities. Developers can also use public methods of Space and Entity.

Run game

GoWorld does not provide a game executable. Developers have to build their own game program. A common game program looks like bellow:

import "goworld"

func main() {
	goworld.RegisterSpace(&MySpace{}) // Register a custom Space type
	// Register service entity types
	goworld.RegisterService("OnlineService", &OnlineService{})
	goworld.RegisterService("SpaceService", &SpaceService{})
	// Register Account entity type
	goworld.RegisterEntity("Account", &Account{})
	// Register Monster entity type
	goworld.RegisterEntity("Monster", &Monster{})
	// Register Player entity type
	goworld.RegisterEntity("Player", &Player{})
	// Run the game server

Basically, you need to register space type, service types and entity types and then start the endless loop of game logic.

Creating Spaces

Use goworld.CreateSpace* functions to create spaces.

Creating Entities

Use goworld.CreateEntity* functions to create entities.

Loading Entities

Use goworld.LoadEntity* functions to load entities from database.

Entity RPC

Use goworld.Call* functions to do RPC among entities

Entity storage and attributes

Each entity type should override function DescribeEntityType to declare its expected behavior and all attributes, just like bellow.

func (a *Avatar) DescribeEntityType(desc *entity.EntityTypeDesc) {
	desc.SetPersistent(true).SetUseAOI(true, 100)
	desc.DefineAttr("name", "AllClients", "Persistent")
	desc.DefineAttr("exp", "Client", "Persistent")
	desc.DefineAttr("lastMailID", "Persistent")
	desc.DefineAttr("testListField", "AllClients")

Function SetPersistent can be used to make entities persistent. Persistent entities' attributes will be marshalled and saved on Entity Storage (e.g. MongoDB) every configurable minutes.

Entities use attributes to store related data. Attributes can be synchronized to clients automatically. An entity's "AllClient" attributes will be synchronized to all clients of entities where this entity is in its AOI range. "Client" attributes wil be synchronized to own clients of entities. "Persistent" attributes will be saved on entity storage when entities are saved periodically. When entity is migrated from one game process to another, all attributes are marshalled and sent to the target game where the entity will be reconstructed using attribute data.


GoWorld uses `goworld.ini` as the default config file. Use '-configfile <path>' to use specified config file for processes.


Package Files

doc.go goworld.go

func AddCallback Uses

func AddCallback(d time.Duration, callback func())

AddTimer adds a timer to be executed after specified duration

func AddTimer Uses

func AddTimer(d time.Duration, callback func())

AddTimer adds a repeat timer to be executed every specified duration

func Call Uses

func Call(id EntityID, method string, args ...interface{})

Call other entities

func CallNilSpaces Uses

func CallNilSpaces(method string, args ...interface{})

CallNilSpaces calls methods of all nil spaces on all games

func CallService Uses

func CallService(serviceName string, method string, args ...interface{})

CallService calls a service entity

func Entities Uses

func Entities() entity.EntityMap

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

func Exists Uses

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

Exists checks if entityID exists in entity storage

returns result in callback

func GetGameID Uses

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 Uses

func GetKVDB(key string, callback kvdb.KVDBGetCallback)

GetKVDB gets value of key from KVDB

func GetOnlineGames Uses

func GetOnlineGames() common.Uint16Set

GetOnlineGames returns all online game IDs

func GetOrPutKVDB Uses

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 GetServiceEntityID Uses

func GetServiceEntityID(serviceName string) common.EntityID

GetServiceEntityID returns the entityid of the service

func ListAttr Uses

func ListAttr() *entity.ListAttr

ListAttr creates a new ListAttr

func ListEntityIDs Uses

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 Uses

func LoadEntityAnywhere(typeName string, entityID EntityID)

LoadEntityAnywhere loads the specified entity from entity storage

func LoadEntityLocally Uses

func LoadEntityLocally(typeName string, entityID EntityID)

LoadEntityLocally load entity in the local game If the entity already exists on any server, LoadEntityLocally will do nothing

func LoadEntityOnGame Uses

func LoadEntityOnGame(typeName string, entityID EntityID, gameid uint16)

LoadEntityOnGame loads entity in the specified game If the entity already exists on any server, LoadEntityOnGame will do nothing

func MapAttr Uses

func MapAttr() *entity.MapAttr

MapAttr creates a new MapAttr

func Post Uses

func Post(callback post.PostCallback)

Post posts a callback to be executed It is almost same as AddCallback(0, callback)

func PutKVDB Uses

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

PutKVDB puts key-value to KVDB

func RegisterCrontab Uses

func RegisterCrontab(minute, hour, day, month, dayofweek int, cb func())

RegisterCrontab a callack which will be executed when time condition is satisfied

param minute: time condition satisfied on the specified minute, or every -minute if minute is negative param hour: time condition satisfied on the specified hour, or every -hour when hour is negative param day: time condition satisfied on the specified day, or every -day when day is negative param month: time condition satisfied on the specified month, or every -month when month is negative param dayofweek: time condition satisfied on the specified week day, or every -dayofweek when dayofweek is negative param cb: callback function to be executed when time is satisfied

func RegisterEntity Uses

func RegisterEntity(typeName string, entityPtr entity.IEntity) *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 RegisterService Uses

func RegisterService(typeName string, entityPtr entity.IEntity)

RegisterService registeres an service type After registeration, the service entity will be created automatically on some game

func RegisterSpace Uses

func RegisterSpace(spacePtr entity.ISpace)

RegisterSpace registers the space entity type.

All spaces will be created as an instance of this type

func Run Uses

func Run()

Run runs the server endless loop

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

type Entity Uses

type Entity = entity.Entity

Entity type is the type of any entity in game

func CreateEntityLocally Uses

func CreateEntityLocally(typeName string) *Entity

CreateEntityLocally creates a entity on the local server

returns EntityID

func GetEntity Uses

func GetEntity(id EntityID) *Entity

GetEntity gets the entity by EntityID

type EntityID Uses

type EntityID = common.EntityID

EntityID is a global unique ID for entities and spaces. EntityID is unique in the whole game server, and also unique across multiple games.

func CreateEntityAnywhere Uses

func CreateEntityAnywhere(typeName string) EntityID

CreateEntitySomewhere creates a entity on any server

func CreateEntityOnGame Uses

func CreateEntityOnGame(gameid uint16, typeName string) EntityID

func CreateSpaceAnywhere Uses

func CreateSpaceAnywhere(kind int) EntityID

CreateSpaceAnywhere creates a space with specified kind in any game server

func CreateSpaceOnGame Uses

func CreateSpaceOnGame(gameid uint16, kind int) EntityID

CreateSpaceOnGame creates a space with specified kind on the specified game

returns the space EntityID

func GetNilSpaceID Uses

func GetNilSpaceID(gameid uint16) EntityID

GetNilSpaceID returns the Entity ID of nil space on the specified game

type Space Uses

type Space = entity.Space

Space is the type of spaces

func CreateSpaceLocally Uses

func CreateSpaceLocally(kind int) *Space

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

returns the space EntityID

func GetNilSpace Uses

func GetNilSpace() *Space

GetNilSpace returns the nil space on this game Nil space is a special space with Kind = 0. Nil space is the default space for all created entities. Each game has one nil space with fixed EntityID for each game, which can be acquired by calling `GetNilSpaceID`

Since nil game exists on each game with fixed EntityID, an entity can migrate to target game by calling `e.EnterSpace(GetNilSpaceID(gameid), Vector3{})`

func GetSpace Uses

func GetSpace(id EntityID) *Space

GetSpace gets the space by ID

type Vector3 Uses

type Vector3 = entity.Vector3

Export useful types


engine/lib/gwsnappyPackage snappy implements the snappy block-based compression format.

Package goworld imports 10 packages (graph). Updated 2018-08-14. Refresh now. Tools for package owners.