{"id":15065760,"url":"https://github.com/metagogs/gogs","last_synced_at":"2025-04-09T13:04:46.097Z","repository":{"id":58873383,"uuid":"533137537","full_name":"metagogs/gogs","owner":"metagogs","description":"gogs is a simple, fast and lightweight game server framework written in golang","archived":false,"fork":false,"pushed_at":"2025-03-24T13:30:00.000Z","size":818,"stargazers_count":58,"open_issues_count":5,"forks_count":12,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-04-02T12:07:59.366Z","etag":null,"topics":["android","datachannel","game","game-framework","gameserver","go","goalng-application","ios","protobuf","unity","webrtc","websocket"],"latest_commit_sha":null,"homepage":"","language":"Go","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/metagogs.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":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-09-06T02:50:54.000Z","updated_at":"2025-03-18T14:35:10.000Z","dependencies_parsed_at":"2023-11-24T01:31:54.320Z","dependency_job_id":"63ab935a-da5a-40e7-b097-30f92ebc93a5","html_url":"https://github.com/metagogs/gogs","commit_stats":{"total_commits":174,"total_committers":5,"mean_commits":34.8,"dds":0.3793103448275862,"last_synced_commit":"9de4b934e9d4a46a3669b76674b22e78dfb3e7e9"},"previous_names":[],"tags_count":23,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/metagogs%2Fgogs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/metagogs%2Fgogs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/metagogs%2Fgogs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/metagogs%2Fgogs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/metagogs","download_url":"https://codeload.github.com/metagogs/gogs/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248045230,"owners_count":21038553,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["android","datachannel","game","game-framework","gameserver","go","goalng-application","ios","protobuf","unity","webrtc","websocket"],"created_at":"2024-09-25T00:47:29.096Z","updated_at":"2025-04-09T13:04:46.079Z","avatar_url":"https://github.com/metagogs.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# gogs: Golang Game Server Framework\n\n\n[![version](https://img.shields.io/github/v/tag/metagogs/gogs?label=version)](https://github.com/metagogs/gogs)\n[![codecov](https://codecov.io/gh/metagogs/gogs/branch/main/graph/badge.svg?token=CLNQZ26H6X)](https://codecov.io/gh/metagogs/gogs)\n![GitHub issues](https://img.shields.io/github/issues/metagogs/gogs)\n![GitHub Workflow Status](https://img.shields.io/github/workflow/status/metagogs/gogs/Go)\n![GitHub Release Date](https://img.shields.io/github/release-date/metagogs/gogs)\n![GitHub last commit](https://img.shields.io/github/last-commit/metagogs/gogs)\n[![goversion](https://img.shields.io/github/go-mod/go-version/metagogs/gogs)](https://github.com/metagogs/gogs)\n[![license](https://img.shields.io/github/license/metagogs/gogs)](https://github.com/metagogs/gogs)\n![GitHub top language](https://img.shields.io/github/languages/top/metagogs/gogs)\n\n\n\ngogs 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.\n\n[Untiy Meta City Demo Online](https://metagogs.github.io/metacity/)\n\n---\n\n## TODO\n- [ ] Support metrics\n- [x] Support generate Unity C# SDK\n- [ ] Support generate JS SDK\n- [ ] Support generate Golang SDK\n- [ ] Support Remote call\n- [ ] Support tracing\n- [x] Support gogs generate docker file\n- [x] Support gogs generate k8s yaml\n- [ ] Support custom game packet protocol\n- [ ] Support kubegame controller, create game pod with api\n- [ ] Add more examples\n- [ ] Add more tests\n- [ ] Add more documentation\n- [ ] Test coverage reaches 80% \n- [ ] k8s friendly, hot reload?\n\n\n## Getting Started\n### Prerequisites\n* [Go](https://golang.org/) \u003e= 1.21\n* [Protobuf](https://developers.google.com/protocol-buffers)\n### Init your project\ninstall the gogs\n```\ngo install github.com/metagogs/gogs/tools/gogs@v0.2.4\n```\ninit project\n```\nmkdir yourgame\ncd yourgame\ngogs init -p yourgame\n\nFlags:\n -p your go package name\n```\nedit your proto, add the game message, then generate the code\n```\ngogs go -f data.proto\n\nFlags:\n -f proto file path\n```\nrun your game server\n```\ngo mod tidy\ngo run main.go\n```\n### Generated Project\n```\ninternal/\n    logic/\n        baseworld/\n            bind_user_logic.go\n    server/\n        server.go\n    svc/\n        service_context.go\nmodel/\n    data.ep.go\n    data.pb.go\nconfig.yaml     \ndata.proto      \nmain.go\n```\n\n### Generated Unity C# Code\nthis will generate a unity code, you can use it to test your game server. And you need use the [Unity Protobuf](./unity) to run the code.\n```\n gogs csharp -f data.proto\n\n Flags:\n -f proto file path\n -g generate unity c# gogs library, you should use it when you generate code first time\n```\n\n### Deployment\n```\ngogo docker // generate Dockerfile\n\ngo run main --deployment // generate k8s yaml\n--svc use service to expose your game server not hostport\n--name your game server name\n--namepsace your k8s namespace\n```\n\n## How to encode/decode the message\n### Packet Protocol\ngogs uses 8 bytes as the protocol header\n\nprotocol header = flag + version + action index + message data length\n```\n0     byte  flag         8bit    protocol flag, awalys 0x7E \n1     byte  version      5bit    protocel version\n            encodeType   3bit    protocel encode type\n2     byte  packetType   2bit    packet message type 1 system 2 server\n            component    6bit    message component index\n3.4   byte  action       16bit   message action index\n5.6.7 byte  length       24bit   message length\n```\n\n### What is the action index\n\naction index = packetType + component index + action index\n```protobuf\n// @gogs:Components\nmessage Components {\n    BaseWorld BaseWorld = 1; // 1 is the component index\n}\n\nmessage BaseWorld {\n    BindUser BindUser = 1; // 1 is the action index\n\n    BindSuccess BindSuccess = 2; // 2 is the action index\n}\nmessage BindUser {\n    string uid = 1;\n}\n\n\n// @gogs:ServerMessage\nmessage BindSuccess {\n}\n```\n\nlike this proto, the BindUser and BindSuccess is the message comunication between client and server\n\nBindUser action index = packetType \u003c\u003c22 | component \u003c\u003c16 | action = 2 \u003c\u003c 22 | 1 \u003c\u003c 16 | 1 = 0x810001\n\nBindSuccess action index = packetType \u003c\u003c22 | component \u003c\u003c16 | action = 2 \u003c\u003c 22 | 1 \u003c\u003c 16 | 2 = 0x810002\n\n### Packet encode \u0026 decode\ngogs has three encode\u0026decode types - encodeType in protocol header\n- 0 json encode\u0026decode without protocol header\n- 1 json encode\u0026decode with protocol header\n- 2 protobuf encode\u0026decode with protocol header\n\n### Packet message\n\n**message with encode type 0 (json without protocol header)**\n\nmessage = **JSON binary data**\n\n`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`\n\n```json\n{\n\t\"action\": \"BindUser\",\n\t\"uid\": \"123\"\n}\n```\n\n```golang\napp.UseDefaultEncodeJSONWithHeader()\n```\n\n---\n**message with encode type 1 (json with protocol header)**\n\nmessage = **8 bytes protocol header** + **JSON binary data**\n\n```golang\napp.UseDefaultEncodeJSON()\n```\n---\n**message with encode type 2 (protobuf with protocol header)**\n\nmessage = **8 bytes protocol header** + **protobuf binary data**\n\n```golang\napp.UseDefaultEncodeProto()\n```\n\n\n\n\n## Contributing\n### Running the gogs tests\n```\nmake test\n```\nThis command will run both unit and e2e tests.\n\n\n## Demo\n  + [Base demo generated by gogs](./examples/basedemo)\n  + [Untiy Meta City Demo](https://github.com/metagogs/metacity)\n  + [Untiy Meta City Demo Online](https://metagogs.github.io/metacity/)\n  + [gtc - terminal chat app](https://github.com/szpnygo/gtc)\n  \n## License\n[Apache License Version 2.0](./LICENSE)\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmetagogs%2Fgogs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmetagogs%2Fgogs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmetagogs%2Fgogs/lists"}