{"id":50791417,"url":"https://github.com/cuihairu/civgenesis","last_synced_at":"2026-06-12T11:30:27.202Z","repository":{"id":331162242,"uuid":"1125340207","full_name":"cuihairu/civgenesis","owner":"cuihairu","description":"CivGenesis: a Java 21 Netty WebSocket (binary) game server framework with TLV protocol, annotation-based routing, sharded execution, reliable push/resume, Nacos discovery, and optional Prometheus + OpenTelemetry.","archived":false,"fork":false,"pushed_at":"2026-05-16T03:37:02.000Z","size":318,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-16T05:39:05.385Z","etag":null,"topics":["game-server-framework"],"latest_commit_sha":null,"homepage":"https://cuihairu.github.io/civgenesis/","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cuihairu.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"docs/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-30T14:54:34.000Z","updated_at":"2026-05-16T03:35:15.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/cuihairu/civgenesis","commit_stats":null,"previous_names":["cuihairu/civgenesis"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/cuihairu/civgenesis","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cuihairu%2Fcivgenesis","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cuihairu%2Fcivgenesis/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cuihairu%2Fcivgenesis/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cuihairu%2Fcivgenesis/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cuihairu","download_url":"https://codeload.github.com/cuihairu/civgenesis/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cuihairu%2Fcivgenesis/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34243051,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-12T02:00:06.859Z","response_time":109,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["game-server-framework"],"created_at":"2026-06-12T11:30:26.297Z","updated_at":"2026-06-12T11:30:27.194Z","avatar_url":"https://github.com/cuihairu.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# CivGenesis\n\n[![CI](https://github.com/cuihairu/civgenesis/actions/workflows/ci.yml/badge.svg)](https://github.com/cuihairu/civgenesis/actions/workflows/ci.yml)\n[![Docs](https://github.com/cuihairu/civgenesis/actions/workflows/docs.yml/badge.svg)](https://github.com/cuihairu/civgenesis/actions/workflows/docs.yml)\n[![codecov](https://codecov.io/gh/cuihairu/civgenesis/branch/main/graph/badge.svg)](https://codecov.io/gh/cuihairu/civgenesis)\n![Java](https://img.shields.io/badge/Java-21-007396?logo=openjdk\u0026logoColor=white)\n![Spring%20Boot](https://img.shields.io/badge/Spring%20Boot-3.4.1-6DB33F?logo=springboot\u0026logoColor=white)\n![Gradle](https://img.shields.io/badge/Gradle-9.2.1-02303A?logo=gradle\u0026logoColor=white)\n[![License](https://img.shields.io/github/license/cuihairu/civgenesis)](LICENSE)\n\nJava 21 / Spring Boot / Netty game server framework for building real-time game backends with a custom WS binary protocol, annotation-based routing, sharded execution, reliable push/resume, observability, and service discovery.\n\nThis repository contains framework/runtime code only (no gameplay/business logic).\n\nLicense: Apache-2.0 (see `LICENSE`).\n\n## Why CivGenesis\n\n- Netty-only message pipeline (no Spring MVC/Tomcat in the hot path)\n- Custom protocol: WebSocket Binary + TLV envelope (extensible, skip-unknown) + Protobuf payload\n- Req/Resp with dedup-friendly `seq` (server-side dedup + timeout), plus reliable push with `ACK_REQUIRED` + resume window\n- Sharded execution model for game state (by `playerId` / channel)\n- Optional Prometheus metrics + OpenTelemetry tracing\n- Nacos-based service discovery + gRPC/IPC integration points\n\n## Architecture\n\n```mermaid\nflowchart LR\n  subgraph Client\n    U[Unity SDK]:::c\n    T[TS SDK - Cocos/LayaAir]:::c\n  end\n\n  U --\u003e|WS Binary + TLV| WS\n  T --\u003e|WS Binary + TLV| WS\n\n  subgraph GameGateway[\"Game Gateway - Netty\"]\n    WS[Netty WebSocket Server]:::s\n    DEC[TLV Frame Decoder/Encoder]:::s\n    DISP[Dispatcher Runtime - @GameController/@GameRoute]:::s\n    SHARD[Shard Executor - player/channel]:::s\n    SCHED[HashedWheel Scheduler]:::s\n  end\n\n  WS --\u003e DEC --\u003e DISP --\u003e SHARD\n  SHARD --\u003e|invoke handler| H[Game Handlers - your code]:::a\n  H --\u003e|RESP/PUSH| DISP\n  SCHED --\u003e SHARD\n\n  subgraph Infra[\"Infra\"]\n    NACOS[Nacos Registry/Discovery]:::i\n    GRPC[gRPC / IPC endpoints]:::i\n    OBS[Prometheus / OTel]:::i\n    JOBS[Jobs Runner - local + leader-only SPI]:::i\n  end\n\n  DISP --- OBS\n  WS --- OBS\n  JOBS --- OBS\n  DISP --- GRPC\n  GRPC --- NACOS\n  classDef c fill:#1f2937,stroke:#0b1220,color:#ffffff\n  classDef s fill:#0ea5e9,stroke:#075985,color:#ffffff\n  classDef a fill:#22c55e,stroke:#15803d,color:#ffffff\n  classDef i fill:#a855f7,stroke:#6b21a8,color:#ffffff\n```\n\n## Repo layout\n\n```\n.\n├── civgenesis-core/                 # protocol, errors, sharded executors, observability SPI\n├── civgenesis-codec-tlv/            # TLV varint codec\n├── civgenesis-protocol-system/      # system.proto (reserved msgId range)\n├── civgenesis-codec-protobuf/       # protobuf payload codec + system Error\n├── civgenesis-dispatcher/           # @GameController/@GameRoute + route scan + dispatcher runtime\n├── civgenesis-scheduler/            # hashed wheel scheduler (time wheel)\n├── civgenesis-transport-netty-ws/   # Netty WebSocket transport\n├── civgenesis-transport-netty-tcp/  # Netty TCP transport (length-prefixed)\n├── civgenesis-registry/             # registry/discovery SPI\n├── civgenesis-registry-nacos/       # Nacos implementation\n├── civgenesis-rpc-grpc/             # gRPC helpers\n├── civgenesis-jobs/                 # background jobs (local + leader-only lease SPI)\n├── civgenesis-jobs-lease-redis/     # optional Redis LeaseProvider reference impl\n├── civgenesis-ipc/                  # IPC reference impl (UDS) + InstanceId helpers\n├── civgenesis-ipc-aeron/            # IPC reference impl (Aeron IPC / SHM)\n├── civgenesis-spring-boot-starter/  # auto-wiring (no MVC), properties, lifecycle\n├── clients/\n│   ├── unity/                       # Unity (C#) client SDK (protocol + connection mgmt)\n│   └── ts/                          # TypeScript client SDK (Cocos/LayaAir)\n├── examples/\n│   └── echo-server/                 # minimal server example (no gameplay logic)\n└── docs/                            # VuePress docs (published via GitHub Pages)\n```\n\n## Design principles (high-level)\n\n- Keep the hot path minimal: Netty -\u003e decode -\u003e dispatch -\u003e shard -\u003e handler\n- Prefer deterministic state handling: shard by `playerId` for ordered execution\n- Treat reliability as a protocol feature: `seq` for Req/Resp retries; `pushId` + `ACK_REQUIRED` for reliable push\n- Prefer “resume window, else full sync”: small gap replay, large gap snapshot\n- Observability is opt-in but first-class: metrics \u0026 tracing should be cheap when disabled\n\n## Quick start (server)\n\nSpring Boot is used for wiring/lifecycle only. Game messages do not go through Spring MVC.\n\n1) Add dependency (your app)\n\n```kotlin\ndependencies {\n  implementation(\"io.github.cuihairu:civgenesis-spring-boot-starter:\u003cversion\u003e\")\n}\n```\n\n2) Write routes\n\n```java\n@GameController\npublic class EchoController {\n  @GameRoute(id = 1000, open = true)\n  public void echo(RequestContext ctx, EchoReq req) {\n    ctx.reply(EchoResp.newBuilder().setText(req.getText()).build());\n  }\n}\n```\n\n3) Provide system integrations (required)\n\n- Implement token authentication for `Resume`:\n  - SPI: `io.github.cuihairu.civgenesis.system.auth.TokenAuthenticator`\n- Implement snapshot generation for `SyncSnapshot` (recommended):\n  - SPI: `io.github.cuihairu.civgenesis.system.snapshot.SnapshotProvider`\n\n4) Configure\n\n```yaml\ncivgenesis:\n  dispatcher:\n    enabled: true\n    shards: 64\n  ws:\n    enabled: true\n    port: 8080\n    path: /ws\n```\n\n## Docs\n\n- Docs index: `docs/README.md`\n- Quickstart (example app): `docs/QUICKSTART.md`\n- GitHub Pages (CI published): `https://cuihairu.github.io/civgenesis/`\n- Protocol: `docs/PROTOCOL.md`\n- Protobuf workflow: `docs/PROTOBUF.md`\n- Dispatcher/routing: `docs/DISPATCHER.md`\n- Observability: `docs/OBSERVABILITY.md`\n- Jobs (local/distributed): `docs/JOBS.md`\n- Client SDKs: `docs/CLIENT_SDK.md`\n- Integration (admin/gateway/login): `docs/INTEGRATION.md`\n\n## Client SDKs (protocol only)\n\n- Unity（C#）：`clients/unity/`\n- TypeScript（Cocos/LayaAir）：`clients/ts/`\n\n## Build\n\n```bash\n./gradlew build\n```\n\n## Docs site (VuePress)\n\nLocal preview:\n\n```bash\nnpm ci\nnpm run docs:dev\n```\n\nBuild static site:\n\n```bash\nnpm ci\nnpm run docs:build\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcuihairu%2Fcivgenesis","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcuihairu%2Fcivgenesis","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcuihairu%2Fcivgenesis/lists"}