English | 简体中文

Golaxy Distributed Service Development Framework is the service-side companion to Golaxy Core. It builds a distributed service runtime on top of the EC system and actor-thread model, and packages the infrastructure commonly needed by real-time systems such as game servers, gateways, and remote control platforms.

This repository is organized around three layers:

• framework: application bootstrap, service/runtime assembly, lifecycle hooks, and entity/component helpers.
• addins: reusable infrastructure integrations such as broker, discovery, router, RPC, gateway, and database access.
• net: the protocol stack used by the communication layer, including GTP transport and GAP application messages.

• App collects service assemblers, loads CLI/configuration with Cobra and Viper, and starts the requested service replicas.
• IService wraps a service context and exposes add-ins such as broker, discovery, distributed sync, distributed service, distributed entity query, and RPC.
• IRuntime wraps a runtime context, installs runtime add-ins, and owns entity execution.
• EntityBehavior and ComponentBehavior provide typed access back to the owning runtime and service.
• BuildRuntime, BuildEntityPT, and BuildEntity are the main builder APIs for runtime and entity creation.

Unless a service or runtime installs its own implementation during lifecycle hooks, the framework assembles these add-ins automatically.

Service-level defaults:

• log
• conf
• broker via NATS
• discovery via ETCD
• dsync via ETCD
• dsvc
• dent querier
• rpc

Runtime-level defaults:

• log
• rpcstack
• dent registry

• Bootstrap stateful or stateless services with configurable replica counts.
• Load configuration from flags, environment variables, local files, or Viper remote providers.
• Discover services, advertise nodes, and issue future-based inter-service calls.
• Register and query distributed entities across runtimes and services.
• Use a built-in broker layer, distributed synchronization, and SQL/Redis/MongoDB integrations.
• Serve long-lived TCP/WebSocket connections with the GTP transport stack.
• Exchange routed messages and RPC requests/replies with GAP messages and variant payloads.
• Build gateways, routers, service RPC processors, and RPC clients from shared protocol components.

package main

import "git.golaxy.org/framework"

type LobbyService struct {
	framework.ServiceBehavior
}

func (svc *LobbyService) OnStarted(s framework.IService) {
	s.BuildRuntime().
		SetName("main").
		SetEnableFrame(true).
		SetFPS(20).
		New()
}

func main() {
	framework.NewApp().
		SetAssembler("lobby", &LobbyService{}).
		Run()
}

The service name passed to SetAssembler is used as:

• the configuration subtree returned by svc.ServiceConf()
• the default key inside startup.services
• the logical service name announced by distributed-service related add-ins

App registers a common set of flags before boot:

Typical startup command:

your-app \
  --startup.services lobby=2 \
  --nats.address localhost:4222 \
  --etcd.address localhost:2379 \
  --conf.local_path ./config.yaml

Service-specific settings should live under the service name:

lobby:
  tick_interval: 50ms
  gate:
    tcp_address: 0.0.0.0:7001

Inside service code, svc.ServiceConf() resolves to the lobby subtree while svc.AppConf() still exposes the full merged configuration.

• net/gtp is the transport layer. It defines handshake messages, cipher negotiation, authentication, compression, and reliable packet delivery over TCP or WebSocket.
• net/gap sits above GTP or broker-delivered payloads. It carries forwarded messages, RPC requests/replies, one-way RPC, and extensible application payloads.
• addins/gate, addins/router, and addins/rpc build service-facing communication features on top of those two layers.

• Go 1.25+
• NATS for the default broker add-in
• ETCD for the default discovery, distributed sync, and distributed entity registry/query add-ins
• Optional Redis if you choose Redis-backed distributed sync or Redis DB access
• Optional MongoDB or SQL databases depending on the enabled DB add-ins

go get -u git.golaxy.org/framework

See pangdogs/examples for end-to-end services, gateways, and RPC usage.

• Golaxy Distributed Service Development Framework Core
• Golaxy Game Server Scaffold