Cherry is a Go game server framework built on the Actor Model for teams building MMO, SLG, and RPG backends that need to scale to millions of players across distributed nodes.

What it is

Cherry is a distributed game server framework written in Golang that organises game logic around the Actor Model: every Actor runs on its own goroutine and processes messages serially from independent FIFO queues for local client requests, cross-node remote calls, and system events. It lives in the Go game-server ecosystem and assembles into a running service through a chained Builder API — Register, SetSerializer, AddActors, Startup — with a defined lifecycle of Register → Set → Init → OnAfterInit → OnBeforeStop → OnStop, stopping components in reverse registration order.

The concrete problem it solves is the plumbing a multiplayer backend otherwise has to build by hand: clustered node discovery, cross-node RPC, session handling for connected clients, protocol framing, and garbage-collection pressure under high message volume. It replaces that scattered assembly with pluggable connectors (TCP, WebSocket, HTTP server and client), NATS-backed transport for remote calls, NATS or etcd for membership discovery, and object-pooled messaging that passes messages within a process without serialization at all. Its protocol layer includes a Pomelo-compatible frame (type(1b) + length(3b) + data) alongside a lighter Simple format (id(4b) + dataLen(4b) + data).

Key capabilities

• Three switchable discovery backends selected from the profile: default for single-process development, nats for master/slave heartbeat discovery, and etcd using lease + watch for multi-node production.
• Cross-node RPC over NATS with synchronous and asynchronous invocation and configurable timeouts, plus discovery APIs such as Map(), ListByType("game"), Random("gate"), UpdateSetting(), and OnAddMember / OnRemoveMember callbacks.
• Four built-in connectors — TCP, WebSocket, HTTP Server, and HTTP Client — with a protocol parser and session management layer that handles agent Actors on frontend nodes.
• Zero-allocation message passing via a sync.Pool message pool with reference counting, Protobuf as the default serializer with JSON also supported, and automatic ClusterPacket encoding for cross-node messages.
• Actor-level features including child Actors that share their parent's lifecycle and route through it, plus timers and scheduled tasks that execute on the Actor's own goroutine.
• An Extend library of 21 utility packages, including a layered time_wheel scheduler, snowflake for distributed unique IDs, nuid, compress, crypto, gob, mapstructure, and a cached regex.
• Lifecycle hooks driven by SIGINT, SIGQUIT, and SIGTERM for graceful shutdown, with tiered error codes covering sessions (10+) and RPC failures (20+).

Who uses it and how

• Backend teams shipping MMO, SLG, or RPG titles that need multiple node types — frontend gate nodes receiving client connections and backend game nodes behind them — clustered together.
• Studios moving off Pomelo, since the built-in Pomelo wire format keeps existing multi-platform client SDKs working against the new server.
• Operators running multi-node production deployments on NATS or etcd discovery, where members join and leave at runtime and settings are broadcast automatically to all nodes.
• Developers working single-process in local development, using the default discovery mode and a profile file such as etc/profile/dev.json with no cluster infrastructure.
• Teams concerned with GC behaviour at scale, using the object-pooled message path and Protobuf serialization to reduce allocation under sustained message load.

Getting started

Install with go get github.com/cherry-game/cherry (Go 1.24+ is required), then start an app with cherry.Configure("etc/profile/dev.json", "game-1", true, cherry.Cluster).Startup(); full documentation is available at https://cherry-game.github.io.

How it compares

Cherry sits alongside Pomelo and Pitaya as a choice for Node developers who want the same cluster-and-connector model implemented in Go, and its Pomelo-compatible framing is the clearest bridge between them. Among the tools named in its own topic list it is the one built explicitly on Go's Actor Model with per-actor goroutines and NATS/etcd discovery, rather than on a different runtime or transport.

When to use it — and when not

A team adopting Cherry must be prepared to operate NATS (and, if chosen, an etcd instance) alongside their game nodes, and to manage profile configuration and node IDs across the cluster. It is a poor fit for teams that only need a single-process server, that are already committed to a non-Go stack, or that depend heavily on English-language documentation, since the README is largely Chinese with the English version in a separate README.en.md. Note also that etcd discovery is delivered from a separate repository rather than the main module.

go get github.com/cherry-game/cherry

package main

import (
    cherry "github.com/cherry-game/cherry"
)

func main() {
    app := cherry.Configure(
        "etc/profile/dev.json", // profile 路径
        "game-1",               // 节点 ID
        true,                   // 是否前端节点（接收客户端连接）
        cherry.Cluster,         // 集群模式
    )
    app.Startup()
}

cherry.Configure("etc/profile/dev.json", "game-1", true, cherry.Cluster).
    Register(myComponent).
    SetSerializer(cherryFacade.NewProtobuf()).
    AddActors(myActor).
    Startup()

Register → Set → Init → OnAfterInit → (运行中) → OnBeforeStop → OnStop

type MyActor struct {
    capp.ActorLogger
}

func (p *MyActor) OnInit() {
    p.Local().Register("myHandler", p.handle)
    p.Remote().Register("myRemote", p.remote)
    p.EventRegister("eventName", p.onEvent)
}

func (p *MyActor) handle(session *cproto.Session, req *pb.MyReq) {
    p.Response(session, &pb.MyResp{Value: "ok"})
}

discovery := app.Discovery()

// 成员查询
all := discovery.Map()
games := discovery.ListByType("game")
member, ok := discovery.Random("gate")

// Settings 同步（自动广播到所有节点）
discovery.UpdateSetting("region", "us-east")

// 成员变更回调
discovery.OnAddMember(func(m IMember) {
    // 新节点加入
})
discovery.OnRemoveMember(func(m IMember) {
    // 节点离开
})

msg := cherryFacade.GetMessage()
msg.Source = "game-1.player-100"
msg.Target = "map-1.aoi"
msg.FuncName = "enter"
msg.Args = myPayload

// 时间轮 — 调度器、超时、延迟执行
tw := cherryTimeWheel.NewTimeWheel(time.Millisecond*10, 20)
tw.AfterFunc(time.Second, func() { /* ... */ })

// Snowflake 唯一 ID
node, _ := cherrySnowflake.NewNode(1)
id := node.Generate()

if code.IsFail(errCode) {
    p.ResponseCode(session, errCode)
    return
}