gogs

README

gogs: Golang Game Server Framework

gogs is a simple, fast and lightweight game server framework written in golang. It is designed to be easy to use and easy to extend. It will generate logic code from protobuf files, and you can use it to develop your game server. It's also a good starting point for you to learn golang. It supports websocket and webrtc datachannel.

Untiy Meta City Demo Online

---

TODO

• Support metrics
• Support generate Unity C# SDK
• Support generate JS SDK
• Support generate Golang SDK
• Support Remote call
• Support tracing
• Support gogs generate docker file
• Support gogs generate k8s yaml
• Support custom game packet protocol
• Support kubegame controller, create game pod with api
• Add more examples
• Add more tests
• Add more documentation
• Test coverage reaches 80%
• k8s friendly, hot reload?

Getting Started

Prerequisites

• Go >= 1.21
• Protobuf

Init your project

install the gogs

go install github.com/metagogs/gogs/tools/gogs@v0.2.4

init project

mkdir yourgame
cd yourgame
gogs init -p yourgame

Flags:
 -p your go package name

edit your proto, add the game message, then generate the code

gogs go -f data.proto

Flags:
 -f proto file path

run your game server

go mod tidy
go run main.go

Generated Project

internal/
    logic/
        baseworld/
            bind_user_logic.go
    server/
        server.go
    svc/
        service_context.go
model/
    data.ep.go
    data.pb.go
config.yaml     
data.proto      
main.go

Generated Unity C# Code

this will generate a unity code, you can use it to test your game server. And you need use the Unity Protobuf to run the code.

 gogs csharp -f data.proto

 Flags:
 -f proto file path
 -g generate unity c# gogs library, you should use it when you generate code first time

Deployment

gogo docker // generate Dockerfile

go run main --deployment // generate k8s yaml
--svc use service to expose your game server not hostport
--name your game server name
--namepsace your k8s namespace

How to encode/decode the message

Packet Protocol

gogs uses 8 bytes as the protocol header

protocol header = flag + version + action index + message data length

0     byte  flag         8bit    protocol flag, awalys 0x7E 
1     byte  version      5bit    protocel version
            encodeType   3bit    protocel encode type
2     byte  packetType   2bit    packet message type 1 system 2 server
            component    6bit    message component index
3.4   byte  action       16bit   message action index
5.6.7 byte  length       24bit   message length

What is the action index

action index = packetType + component index + action index

// @gogs:Components
message Components {
    BaseWorld BaseWorld = 1; // 1 is the component index
}

message BaseWorld {
    BindUser BindUser = 1; // 1 is the action index

    BindSuccess BindSuccess = 2; // 2 is the action index
}
message BindUser {
    string uid = 1;
}


// @gogs:ServerMessage
message BindSuccess {
}

like this proto, the BindUser and BindSuccess is the message comunication between client and server

BindUser action index = packetType <<22 | component <<16 | action = 2 << 22 | 1 << 16 | 1 = 0x810001

BindSuccess action index = packetType <<22 | component <<16 | action = 2 << 22 | 1 << 16 | 2 = 0x810002

Packet encode & decode

gogs has three encode&decode types - encodeType in protocol header

• 0 json encode&decode without protocol header
• 1 json encode&decode with protocol header
• 2 protobuf encode&decode with protocol header

Packet message

message with encode type 0 (json without protocol header)

message = JSON binary data

gogs retrieves the action index from the message, then gets the filed type and decodes the message, finally it calls the logic function. The json message without protocol header should add a filed named action, the value is the filed name

{
	"action": "BindUser",
	"uid": "123"
}

app.UseDefaultEncodeJSONWithHeader()

---

message with encode type 1 (json with protocol header)

message = 8 bytes protocol header + JSON binary data

app.UseDefaultEncodeJSON()

---

message with encode type 2 (protobuf with protocol header)

message = 8 bytes protocol header + protobuf binary data

app.UseDefaultEncodeProto()

Contributing

Running the gogs tests

make test

This command will run both unit and e2e tests.

Demo

• Base demo generated by gogs
• Untiy Meta City Demo
• Untiy Meta City Demo Online
• gtc - terminal chat app

License

Apache License Version 2.0

Documentation

Index

• Variables
• func BroadcastData(users []string, data []byte, filter *session.SessionFilter, exclude ...string)
• func BroadcastMessage(users []string, send interface{}, filter *session.SessionFilter, ...) error
• func EncodeMessage(in interface{}, name ...string) (*packet.Packet, error)
• func GetSessionByID(id int64) (*session.Session, error)
• func GetSessionByUID(uid string, filter *session.SessionFilter) []*session.Session
• func GetSessionIDsByUID(uid string, filter *session.SessionFilter) ([]int64, []int64)
• func ListSessions() []*session.Session
• func NewBuilder(config *config.Config) *builder
• func SendDataByID(sessionId int64, in []byte)
• func SendMessageByID(sessionId int64, in interface{})
• func SendPacketByID(sessionId int64, in *packet.Packet)
• type App
  • func NewApp(config *config.Config) *App
  • func (app *App) AddAcceptor(acceptor acceptor.Acceptor)
  • func (app *App) GetAcceptors() []acceptor.Acceptor
  • func (app *App) GetSessionPool() session.SessionPool
  • func (app *App) RegisterComponent(sd component.ComponentDesc, ss interface{})
  • func (app *App) RegisterWebHandler(port int, f func(gin *gin.Engine))
  • func (app *App) SetAgentFactory(factory *agent.AgentFactory)
  • func (app *App) Shutdown()
  • func (app *App) Start()
  • func (app *App) UseDefaultEncodeJSON()
  • func (app *App) UseDefaultEncodeProto()
  • func (app *App) UseDefaultEncodePureJSON()
• type NetworkComponent
  • func NewNetworkComponent(app *App) *NetworkComponent
  • func (s *NetworkComponent) Pong(ctx context.Context, sess *session.Session, pong *proto.Pong)

Variables

var DefaultMessageServer *message.MessageServer

var DefaultSessionPool session.SessionPool

var Version string

Functions

func BroadcastData

func BroadcastData(users []string, data []byte, filter *session.SessionFilter, exclude ...string)

send bytes

func BroadcastMessage

func BroadcastMessage(users []string, send interface{}, filter *session.SessionFilter, exclude ...string) error

BroadcastMessage broadcast message to all sessions except the session with the given id. the filter is used to filter the sessions that should not receive the message. send packet

func EncodeMessage

func EncodeMessage(in interface{}, name ...string) (*packet.Packet, error)

func GetSessionByID

func GetSessionByID(id int64) (*session.Session, error)

func GetSessionByUID

func GetSessionByUID(uid string, filter *session.SessionFilter) []*session.Session

GetSessionByUID get session by user id.

func GetSessionIDsByUID

func GetSessionIDsByUID(uid string, filter *session.SessionFilter) ([]int64, []int64)

GetSessionIDsByUID get session by user id. the filter is used to filter the sessions that should not receive the message. result first is the session ids that match the filter, result second is the all session ids with the given uid.

func ListSessions

func ListSessions() []*session.Session

func NewBuilder

func NewBuilder(config *config.Config) *builder

func SendDataByID

func SendDataByID(sessionId int64, in []byte)

func SendMessageByID

func SendMessageByID(sessionId int64, in interface{})

SendMessageByID send message to the session with the given id.

func SendPacketByID

func SendPacketByID(sessionId int64, in *packet.Packet)

Types

type App

type App struct {
	*zap.Logger

	MessageServer *message.MessageServer // 消息管理

	LatencyServer *latency.LatencyServer // 延时服务管理
	GroupServer   *group.GroupServer     // 组管理

	Config *config.Config
	// contains filtered or unexported fields
}

func NewApp

func NewApp(config *config.Config) *App

func (*App) AddAcceptor

func (app *App) AddAcceptor(acceptor acceptor.Acceptor)

func (*App) GetAcceptors

func (app *App) GetAcceptors() []acceptor.Acceptor

func (*App) GetSessionPool

func (app *App) GetSessionPool() session.SessionPool

func (*App) RegisterComponent

func (app *App) RegisterComponent(sd component.ComponentDesc, ss interface{})

func (*App) RegisterWebHandler

func (app *App) RegisterWebHandler(port int, f func(gin *gin.Engine))

func (*App) SetAgentFactory

func (app *App) SetAgentFactory(factory *agent.AgentFactory)

func (*App) Shutdown

func (app *App) Shutdown()

func (*App) Start

func (app *App) Start()

func (*App) UseDefaultEncodeJSON

func (app *App) UseDefaultEncodeJSON()

func (*App) UseDefaultEncodeProto

func (app *App) UseDefaultEncodeProto()

func (*App) UseDefaultEncodePureJSON

func (app *App) UseDefaultEncodePureJSON()

UseDefaultEncodePureJSON 发送消息时不包含头部,使用JSON,方便测试使用,纯JSON 编码有两种，一种是带头部的，一种是不带头部的 PureJSON是不带头部的，类型是写在action里面的

type NetworkComponent

type NetworkComponent struct {
	// contains filtered or unexported fields
}

func NewNetworkComponent

func NewNetworkComponent(app *App) *NetworkComponent

func (*NetworkComponent) Pong

func (s *NetworkComponent) Pong(ctx context.Context, sess *session.Session, pong *proto.Pong)