{"id":25448046,"url":"https://github.com/tfkfan/orbital","last_synced_at":"2025-05-16T07:09:11.273Z","repository":{"id":277856414,"uuid":"919914196","full_name":"tfkfan/orbital","owner":"tfkfan","description":"A blueprint adapting VertX to distributed game server","archived":false,"fork":false,"pushed_at":"2025-05-03T12:28:03.000Z","size":27453,"stargazers_count":14,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-05-03T12:28:46.500Z","etag":null,"topics":["event-loop","game","gamedev","gameserver","high-performance","java","matchmaker","netty","nio","non-blocking","reactive","room","vertx"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tfkfan.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","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,"zenodo":null}},"created_at":"2025-01-21T08:38:58.000Z","updated_at":"2025-04-14T19:12:33.000Z","dependencies_parsed_at":"2025-02-17T15:41:38.311Z","dependency_job_id":"897ef3ad-90f7-405f-839a-fea982538ab9","html_url":"https://github.com/tfkfan/orbital","commit_stats":null,"previous_names":["tfkfan/vertx-game-server","tfkfan/orbital"],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tfkfan%2Forbital","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tfkfan%2Forbital/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tfkfan%2Forbital/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tfkfan%2Forbital/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tfkfan","download_url":"https://codeload.github.com/tfkfan/orbital/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254485051,"owners_count":22078767,"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":["event-loop","game","gamedev","gameserver","high-performance","java","matchmaker","netty","nio","non-blocking","reactive","room","vertx"],"created_at":"2025-02-17T19:18:39.069Z","updated_at":"2025-05-16T07:09:11.267Z","avatar_url":"https://github.com/tfkfan.png","language":"Java","funding_links":[],"categories":["Game development"],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003e\n  \u003cbr\u003e\n  \u003ca href=\"#\"\u003e\u003cimg src=\"logo.svg\" alt=\"header\" width=\"600\"\u003e\u003c/a\u003e\n  \u003cbr\u003e\n  Orbital\n  \u003cbr\u003e\n\u003c/h1\u003e\n\n\u003ch4 align=\"center\"\u003e\nThis is high-performance vert.x based distributed java game server designed for realtime indie multiplayers development\u003c/h4\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://opensource.org/licenses/MIT\" title=\"License: MIT\" \u003e\n    \u003cimg src=\"https://img.shields.io/badge/License-MIT-greenbright.svg?style=flat-square\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n**Project is in active development. Looking for contributors and sponsors to make this stuff widely used in future**\n\nSupports:\n\n* HTTP\n* Websocket\n\nFeatures:\n\n* GameApplication launcher\n* Gateway verticle basic functionality\n* Room verticle basic functionality\n* EventBus-based room listener system\n* 2D geometry\n* Basic rooms\n* Package classes\n* Micrometer + prometheus metrics and monitor web page https://github.com/tfkfan/orbital-monitor\n* Annotation-based incoming message handlers\n* English/Russian web app localization\n\nBacklog:\n\n* GraalVM native image optimizations\n* Grid/Mesh systems and 2D collision models\n* TCP/UDP server mode\n* Advanced room management, player management, admin page https://github.com/tfkfan/orbital-monitor\n* Auth-protected REST API and social accounts oidc providers (google,vk,facebook,X etc...)\n* Advanced basic game objects\n* Payments api integrations\n* Meta game logic tools\n* Infinispan-clustered game server mode\n\n## Core and features\n\nThe solution is based on Vert.X \"Actor\" approach and EventBus features. It allows to have Indefinite amount of\nroom management verticles as workers to process game messages.\nThe code of \"Orbital\" is conceived to be extended and modernized on your own.\nThe basic features are verticles and managers encapsulating business logic of the game.\nFollowing image represents internal framework architecture\n\n![orbital.chart.png](orbital.chart.png)\n\nOrbital cluster is easy reachable according this schema:\n\n![orbital-cluster.chart.png](orbital-cluster.chart.png)\n\n## Usage\n\nSee \"example\" module for complete starter. Please pay attention example already contains frontend resources.\n\n### Requirements\n\nBefore running your first orbital game server your app should have:\n\n- GameManager implementation\n- Player model implementation\n- Game room implementation\n\n### Launch\n\nTo run orbital microcluster with gateway verticle and N room verticles write:\n\n```\npublic static void main(String[] args) {\n    final Vertx vertx = Vertx.vertx();\n\n    int N = 10;\n    new Orbital(vertx)\n                .withConfig(N, new RoomConfig())\n                .withWebsocketGateway(it -\u003e\n                        it.withRouterInitializer(router -\u003e router.route().handler(StaticHandler.create(\"static\")))\n                                .withRouterInitializer(MonitorEndpoint::create))\n                .withGameManagerFactory(config -\u003e DefaultGameManager.factory(config.getRoom()))\n                .withRoomClusterLauncher(pair -\u003e new RoomDeploymentConfig(new DeploymentOptions()\n                        .setThreadingModel(ThreadingModel.VIRTUAL_THREAD)\n                        .setWorkerPoolSize(100)))\n                .run();\n}\n```\n\n## Monitoring\n\n### Setup\n\nTo setup monitor-related instance add required dependency:\n\n```\n\u003cdependency\u003e\n    \u003cgroupId\u003eio.github.tfkfan\u003c/groupId\u003e\n    \u003cartifactId\u003eorbital-monitor\u003c/artifactId\u003e\n    \u003cversion\u003e1.1.0\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\nYour vertx instance should be monitorable this way:\n\n```\nfinal Vertx vertx = new MonitorableVertx().build();\n```\n\nYou can specify certain metrics binders and registries on your own:\n\n```\nfinal Vertx vertx = new MonitorableVertx(registry).build();\n```\n\n```\nfinal Vertx vertx = new MonitorableVertx(registry, new JvmHeapPressureMetrics()).build();\n```\n\nFinal step is static monitor resources linking with gateway verticle:\n\n```\nfinal GatewayVerticle gatewayVerticle = new WebsocketGatewayVerticle(serverConfig, roomConfig)\n                            .withRouterInitializer(MonitorEndpoint::create);\n```\n\n### Web app\n\nThe monitor app allows you to check every metrics:\n\n![orbital.monitor-1.png](orbital.monitor-1.png)\n![orbital.monitor-2.png](orbital.monitor-2.png)\n![orbital.monitor-3.png](orbital.monitor-3.png)\n![orbital.monitor-4.png](orbital.monitor-4.png)\n\n### Endpoints\n\nServer port is 8080 by default\n\n- Monitor web app is available at http://localhost:8085/monitor\n- Prometheus metrics are available at http://localhost:8085/prometheus\n- JSON metrics are available at http://localhost:8085/metrics\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftfkfan%2Forbital","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftfkfan%2Forbital","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftfkfan%2Forbital/lists"}