{"id":18425806,"url":"https://github.com/faforever/server","last_synced_at":"2025-04-12T17:34:26.745Z","repository":{"id":22501544,"uuid":"25841126","full_name":"FAForever/server","owner":"FAForever","description":"The servercode for the Forged Alliance Forever lobby","archived":false,"fork":false,"pushed_at":"2024-06-23T19:10:12.000Z","size":11448,"stargazers_count":67,"open_issues_count":83,"forks_count":63,"subscribers_count":19,"default_branch":"develop","last_synced_at":"2024-06-23T20:21:12.875Z","etag":null,"topics":["game","game-server","hacktoberfest","rts"],"latest_commit_sha":null,"homepage":"http://www.faforever.com","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/FAForever.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"license.rtf","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":"2014-10-27T21:58:37.000Z","updated_at":"2024-06-23T20:21:17.030Z","dependencies_parsed_at":"2023-02-14T02:15:37.088Z","dependency_job_id":"e08362ee-7796-476c-b1e0-a47425d5e751","html_url":"https://github.com/FAForever/server","commit_stats":null,"previous_names":[],"tags_count":96,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FAForever%2Fserver","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FAForever%2Fserver/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FAForever%2Fserver/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FAForever%2Fserver/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/FAForever","download_url":"https://codeload.github.com/FAForever/server/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248605725,"owners_count":21132221,"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":["game","game-server","hacktoberfest","rts"],"created_at":"2024-11-06T05:05:42.825Z","updated_at":"2025-04-12T17:34:26.738Z","avatar_url":"https://github.com/FAForever.png","language":"Python","funding_links":["https://issuehunt.io/r/FAForever/server"],"categories":[],"sub_categories":[],"readme":"# FA Forever - Server\n![Build Status](https://github.com/FAForever/server/actions/workflows/test.yml/badge.svg?branch=develop)\n[![codecov](https://codecov.io/gh/FAForever/server/branch/develop/graph/badge.svg?token=55ndgNQdUv)](https://codecov.io/gh/FAForever/server)\n[![Codacy Badge](https://app.codacy.com/project/badge/Grade/ada42f6e09a341a88f3dae262a43e86e)](https://www.codacy.com/gh/FAForever/server/dashboard?utm_source=github.com\u0026amp;utm_medium=referral\u0026amp;utm_content=FAForever/server\u0026amp;utm_campaign=Badge_Grade)\n[![docs](https://img.shields.io/badge/docs-latest-purple)](https://faforever.github.io/server/)\n[![license](https://img.shields.io/badge/license-GPLv3-blue)](license.txt)\n![python](https://img.shields.io/badge/python-3.10-3776AB)\n\nThis is the source code for the\n[Forged Alliance Forever](https://www.faforever.com/) lobby server.\nClick here to go to the\n[Server Python API Documentation](https://faforever.github.io/server/).\n\n-   For the Lua game mod see\n[faforever/fa](https://github.com/FAForever/fa).\n-   For the official FAF client see\n[faforever/downlords-faf-client](https://github.com/FAForever/downlords-faf-client)\n\n## Overview\nThe lobby server is the piece of software sitting at the very core of FAF,\nenabling players to discover and play games with each other. It is a stateful\nTCP server written in `asyncio` and implements a custom TCP protocol for\ncommunicating with [clients](https://github.com/FAForever/downlords-faf-client).\nThe main responsibilities of the lobby server are:\n-   To manage the lifecycle of joining games\n\n    *(Note that Forged Alliance uses a distributed peer-to-peer networking model,\n    so the simulation happens entirely on the player's machines, and **NOT** on\n    any server)*\n\n-   To facilitate initial connection establishment when players join a game\n\n-   To maintain a list of online players\n\n-   To perform rating calculations and updates\n\nIn production, the lobby server is deployed behind a websocket bridge\n[faforever/ws_bridge_rs](https://github.com/FAForever/ws_bridge_rs).\n\n## Support development\n\nPost a bounty on Issue Hunt. You can reward and financially help developers who\nwork on your issue.\n\n[![Issue hunt](https://github.com/BoostIO/issuehunt-materials/raw/master/v1/issuehunt-button-v1.svg?sanitize=true)](https://issuehunt.io/r/FAForever/server)\n\n## Major Software Dependencies\n\nThe lobby server integrates with a few external services and has been tested\nwith the following versions:\n\n-   MariaDB 10.6\n-   (optional) RabbitMQ 3.9\n\n# Contributing\n\nBefore opening a pull request, please take a moment to look over the\n[contributing guidelines](CONTRIBUTING.md).\n\n## Setting up for development\nFor detailed instructions see the [development guide](DEVELOPMENT.md).\n\n### Quickstart\n*This section assumes you have the necessary system dependencies installed. For\na list of what those are see the [development guide](DEVELOPMENT.md).*\n\n1.  Start up an instance of the FAF database. This is required to run the unit tests\nand development server.\n```\n$ git clone https://github.com/FAForever/faf-stack.git\n$ cd faf-stack\n$ ./scripts/init-db.sh\n```\n\n2.  Install the project dependencies with pipenv\n```\n$ pipenv sync --dev\n```\n\n3.  Run the unit tests or development server\n```\n$ pipenv run tests\n$ pipenv run devserver\n```\n\n# For Client Developers\nThe official FAF client code is available at\n[faforever/downlords-faf-client](https://github.com/FAForever/downlords-faf-client).\nThis can be used as a reference when implementing your own custom client.\n\n## Important Notes\nIn order to avoid having your client break unexpectedly with a new server\nrelease, your server \u003c-\u003e client communication code must adhere to the following\nrules:\n-   Unrecognized server messages are ignored.\n-   Unrecognized fields in messages are ignored.\n\nThis ensures that your client continues to function when new features are\nimplemented on the server side. A new feature might mean that the server will\ninclude a new field in an existing message, or start sending an entirely new\nmessage all together. Such changes are considered to be backwards compatible\nadditions to the server protocol.\n\nYou can read more about the protocol API versioning\n[here](CONTRIBUTING.md#version-numbers).\n\n## Server Protocol\nThere are two layers to the server protocol:\n1. **The wire format.**\nThis is how messages are serialized to bytes and sent over the network stream.\n\n  *NOTE: in production, the client connects to the server via the websocket\n  bridge [faforever/ws_bridge_rs](https://github.com/FAForever/ws_bridge_rs)\n  rather than connecting directly to the TCP port.*\n\n2. **Application level messages.**\nAlso sometimes called 'commands', messages are used to exchange state between\nthe client and server. The client will need to implement appropriate logic for\ninterpreting each message and reacting to it by sometimes updating UI elements,\ninternal state, or launching or terminating external processes.\n\n### Wire Format\nEach message is serialized to a [JSON](https://www.json.org/) object followed\nby an ASCII newline byte (`b\"\\n\"` or `b\"\\x0a\"`). For additional information see\nthe server API documentation:\n[SimpleJsonProtocol](https://faforever.github.io/server/protocol/simple_json.html)\n\n### Application messages\n1. **Request / response type commands.**\n  Most messages that are sent from the client to the server will be acknowledged\n  with a response message. The naming for these messages varies by command. For\n  instance the `ask_session` command will respond with a `session` command\n  containing the session id.\n2. **Asynchronous commands.**\n  Many messages are generated by activity of other users, or asynchronous\n  processes running on the server. These can generate 'broadcast' messages sent\n  out to many connected clients, or direct messages to a specific client without\n  being triggered by a request. Generally 'broadcast' messages are name `*_info`\n  and are used to synchronize the internal states of the server and client, and\n  often signal the need to update some UI elements. For instance the `game_info`\n  message sends updated information about a game that can either be in the lobby\n  state, be actively playing, or have ended.\n\n\nWork is ongoing to document these messages in a comprehensive way. For now, all\ncommands that can be sent from the client -\u003e server can be found via the server\nAPI documentation:\n[LobbyConnection](https://faforever.github.io/server/lobbyconnection.html)\nunder the `command_*` methods. Check the source code for what fields the message\nis expected to have and any possible responses.\n\nIt may also be useful to look at the definitions in the\n[faf-java-commons](https://github.com/FAForever/faf-java-commons/tree/develop/lobby/src/main/kotlin/com/faforever/commons/lobby)\nto see how the official client is deserializing messages from the server.\n\n### Deprecations\nSome fields or entire message classes may become deprecated and marked for\nremoval over time. Actual removal is very rare as it can cause potential\nbreakages of outdated clients. Currently, deprecated fields and messages will\nbe marked with a `# DEPRECATED` comment in the server code and an explanation of\nhow to migrate to the new functionality that is replacing the deprecated field\nor message.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffaforever%2Fserver","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffaforever%2Fserver","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffaforever%2Fserver/lists"}