{"id":25863834,"url":"https://github.com/faforever/faf-pioneer","last_synced_at":"2025-10-08T11:11:38.218Z","repository":{"id":279649914,"uuid":"939033549","full_name":"FAForever/faf-pioneer","owner":"FAForever","description":"FAF ICE Adapter based on WebRTC and the Pion library","archived":false,"fork":false,"pushed_at":"2025-09-12T18:17:47.000Z","size":264,"stargazers_count":0,"open_issues_count":2,"forks_count":6,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-09-12T20:52:59.501Z","etag":null,"topics":["golang","ice","pion","webrtc"],"latest_commit_sha":null,"homepage":"","language":"Go","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/FAForever.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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"patreon":"faf"}},"created_at":"2025-02-25T22:11:33.000Z","updated_at":"2025-09-09T19:56:43.000Z","dependencies_parsed_at":"2025-04-08T07:33:53.600Z","dependency_job_id":"e8511d9b-13cb-4de8-b232-92d433f3c7cb","html_url":"https://github.com/FAForever/faf-pioneer","commit_stats":null,"previous_names":["faforever/faf-pioneer"],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/FAForever/faf-pioneer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FAForever%2Ffaf-pioneer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FAForever%2Ffaf-pioneer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FAForever%2Ffaf-pioneer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FAForever%2Ffaf-pioneer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/FAForever","download_url":"https://codeload.github.com/FAForever/faf-pioneer/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FAForever%2Ffaf-pioneer/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278931654,"owners_count":26070789,"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","status":"online","status_checked_at":"2025-10-08T02:00:06.501Z","response_time":56,"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":["golang","ice","pion","webrtc"],"created_at":"2025-03-02T00:26:39.100Z","updated_at":"2025-10-08T11:11:38.211Z","avatar_url":"https://github.com/FAForever.png","language":"Go","funding_links":["https://patreon.com/faf"],"categories":[],"sub_categories":[],"readme":"# faf-pioneer\nFAF ICE Adapter based on [WebRTC](https://webrtc.org/) and the [Pion project](https://github.com/pion).\nTo understand the problem we are trying to solve, please check our [network architecture](docs/network_architecture.md).\n\n\n\u003cdetails\u003e\n\n\u003csummary\u003eFAF Pioneer application architecture\u003c/summary\u003e\n\n![application-architecture.svg](docs/diagrams/application-architecture.svg)\n\n\u003c/details\u003e\n\n#### Based on modern standards\n\nWebRTC is a specification to send and receive audio, video and any other data to be passed in a peer to peer setup with other users. It used by every modern audio/video conferencing software like Zoom, MS Teams, Google Meeet and many more.\n\nThe Pion library is a first class implementation of the WebRTC spec. The faf-pioneer tries to establish connections between players via ICE (a protocol use by WebRTC) and sends the game data over \"data channels\".\n\n\nIf you want to learn more about it, WebRTC has a is explained very thoroughly in [webrtcforthecurious.com](https://webrtcforthecurious.com/)\n\n## How to run \u0026 test\n\n**!!! This section is subject to change as we are still in a very early stage. !!!**\n\nThe docker-compose.yaml provides you with all services you need to run \u0026 test this application.\n\n* The faf-icebreaker as our signalling server and turn server provider (along with MariaDB \u0026 RabbitMQ as dependencies)\n* Eturnal as a STUN and TURN server\n\nTo set up everything just run\n\n```shell script\ndocker compose up -d\n```\nThis will start all services in the right order and with default configuration.\n\nNow you need to run the faf-pioneer on 2 pcs / VMs. Both need to be able to contact the faf-icebreaker application. You can expose the app via tools like Ngrok.\n\nSo on local machine you run it via\n```shell script\n./run_test_as.sh 1\n```\n\nOn the remote end you have to specify the icebreaker API. This is an example:\n````shell script\nAPI_ROOT=\u003cngrok-url\u003e\u003e ./run_test_as.sh 2\n````\n\nNow to receive data run netcat to listen on port 60000. To send data to the other side send it via netcat to localhost port 18ßßß.\nAlways use UDP here! Also, dependening on your version, you might need to specify IPv4.\n\n### Testing with launcher\n\n#### Using native FAF-Client\n1. Download and checkout `pioneer` branch for [downlords-faf-client](https://github.com/FAForever/downlords-faf-client/tree/pioneer) repository.\n2. Set the launcher environment variable `PIONEER_BIN_NAME` to output binary of `faf-ice`.\n\n#### Using go-emulation of FAF-Client\n\n1. Run the [faf-launcher-emulator](./cmd/faf-launcher-emulator/main.go) with the same arguments \nas [faf-ice](./cmd/faf-ice/main.go)\n2. Run the [faf-ice](./cmd/faf-ice/main.go)\n3. Start the game, an example:\n```\ncd /D C:\\ProgramData\\FAForever\\bin\nForgedAlliance.exe /init init.lua /nobugreport /gpgnet 127.0.0.1:21000 /numgames 11 /numgames 12 /log \"C:\\ProgramData\\FAForever\\logs\\test.log\"\n```\n\n## Data flow\n\nThere is a continuous data flow between this application, the Forged Alliance game, the FAF client and (obviously) the whole stack of these 3 applications on other players computers.\n\nMore details can be found in [GPGnet protocol docs](docs/gpgnet.md).\n\n### Local launch order\n(Work in Progress)\n1. The FAF client launches this ICE adapter and waits for it to signal readiness.\n    * In prior iterations this was due to the ICE adapter running an RPC server and the FAF client successfully connecting to it. \n2. The FAF client launches the Forged Alliance game.\n3. The Forged Alliance game connects to the TCP server for the GpgNet port, that the FAF client has passed to both the ICE adapter and the game.\n4. The Forged Alliance game send a `GameState=Idle` message to the ICE adapter.\n5. The FAF client tells the ICE adapter to host or join a game (using `CreateLobby` and right after it `HostGame` packets).\n6. The ICE adapter tells the game to open a lobby with a predefined udp port.\n7. The FAF client tells the game through the ICE adapter whom to connect to.\n\n### faf-icebreaker REST API\n\nThe icebreaker API can be looked up in SwaggerUI. Once started via docker compose, you can find at\nat http://localhost:8080/q/swagger-ui/.\n\n## Glossary\n\nDue to the long arching history of connectivity among the history of the Forged Alliance Forever, a confusing terminology has established.\n\n* ICE Adapter\n  * An adapter application between the FAF client and the game that orchestrates the communication so that connectivity to other players is done externally (in this iteration via WebRTC, in prior iteration via ICE and local socket handling).\n* Icebreaker\n  * The new signalling server.\n  * Grants access to the list of available STUN and TURN servers along with session based credentials.\n* Lobby server\n  * The service that the FAF client uses to manage game lobbies and initiate information on who plays with whom. In prior ICE adapter iterations it also had the role of the signalling server proxied via the FAF client.\n* RPC connection\n  * In prior iterations the FAF client communicated with the ICE adapter via JSON-RPC 2.0\n  * The ICE adapter was the host.\n* GpgNet\n  * A binary TCP protocol for exchanging messages between the game and the lobby server.\n  * The ICE adapter is acting as a server and the game connects to it. The port is specified as launch parameter of both applications.\n  * Due to WebRTC/ICE changing ports and ip addresses, the ICE adapter has to read, intercept and modify some of the messages.\n  * The protocol can be extended for more messages via SIM mods or game patches. Thus the adapter needs to handle and pass through all unknown messages to ensure compatibility.\n\n## Contribute\n\nThis is the first Go application in FAForever project. We have absolutely no Go experience so far. If we do not follow best practices and you have improvements, all help is welcome.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffaforever%2Ffaf-pioneer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffaforever%2Ffaf-pioneer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffaforever%2Ffaf-pioneer/lists"}