{"id":23187995,"url":"https://github.com/topfreegames/libpitaya","last_synced_at":"2025-11-15T10:02:19.022Z","repository":{"id":33376725,"uuid":"128069735","full_name":"topfreegames/libpitaya","owner":"topfreegames","description":"a client sdk for pitaya game server framework","archived":false,"fork":false,"pushed_at":"2024-02-16T15:21:04.000Z","size":334097,"stargazers_count":70,"open_issues_count":29,"forks_count":40,"subscribers_count":33,"default_branch":"master","last_synced_at":"2025-03-29T21:04:52.518Z","etag":null,"topics":["cplusplus","distributed-systems","game","game-development","game-framework","game-server","library","pitaya","sdk"],"latest_commit_sha":null,"homepage":"","language":"C","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/topfreegames.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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":"2018-04-04T13:56:25.000Z","updated_at":"2025-02-05T06:02:07.000Z","dependencies_parsed_at":"2024-02-16T16:48:15.244Z","dependency_job_id":null,"html_url":"https://github.com/topfreegames/libpitaya","commit_stats":null,"previous_names":[],"tags_count":88,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/topfreegames%2Flibpitaya","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/topfreegames%2Flibpitaya/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/topfreegames%2Flibpitaya/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/topfreegames%2Flibpitaya/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/topfreegames","download_url":"https://codeload.github.com/topfreegames/libpitaya/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247406088,"owners_count":20933803,"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":["cplusplus","distributed-systems","game","game-development","game-framework","game-server","library","pitaya","sdk"],"created_at":"2024-12-18T11:11:52.065Z","updated_at":"2025-11-15T10:02:13.967Z","avatar_url":"https://github.com/topfreegames.png","language":"C","funding_links":[],"categories":["C"],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://ci.appveyor.com/project/leohahn/libpitaya\"\u003e\u003cimg src=\"https://ci.appveyor.com/api/projects/status/326391ofs0q26s0d/branch/master?svg=true\u0026passingText=Windows\" alt=\"Windows Build Status\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n# Attention\n\nLibpitaya is currently under development and is not yet ready for production use. We are working on tests and better documentation and we'll update the project as soon as possible.\n\nLibpitaya C# binding for 4.0.0 and above require Unity 2019.3 to work.\n\n# Libpitaya\n\nLibpitaya is a SDK for building clients for projects using the pitaya game server framework and is built on top of [libpomelo2](https://github.com/NetEase/libpomelo2)\n\n## Building\nLibpitaya is build using CMake. A standard build for linux could be something like:\n\n```bash\ncd libpitaya\ncmake -H. -B_builds/linux -DBUILD_SHARED_LIBS=ON -DCMAKE_BUILD_TYPE=Release\ncmake --build _builds/linux\n```\n\nBelow we show how to build for all major platforms.\n\n**NOTE**: In the `Makefile` there are helper targets that allow you to build for different platforms. Libpitaya is primarly developed to be used from other programming languages aside from C and C++, however, it should be possible to include the libpitaya CMake target from another CMake project using `add_subdirectory`.\n\n### Building for Android\n\n```bash\n# Pick the correct setup for your platform\nmake setup-android-mac\nmake setup-android-linux\n# Build\nmake build-android\n```\n\nThe Android binary will be under `_builds/android/libpitaya-android.so`\n\n### Building for Mac\n\n```\nmake setup-mac\nmake build-mac\n```\nThe Mac binary will be under `_builds/mac/libpitaya-mac.bundle`\n\n### Building for iOS physical devices\n\n```bash\nmake setup-mac\nmake build-ios\n```\nThe iOS binary will be under `_builds/ios/libpitaya-ios.a`\nOn iOS, this library will be compiled statically which means you *must* include in your project the dependencies `libz.a`,`libuv_a.a`,`libssl.a` and `libcrypto.a` as well.\n\n\n### Building for iOS simulators\n\n```bash\nmake setup-mac\nmake build-ios-simulator\n```\nThe iOS binary will be under `_builds/ios-simulator/libpitaya-ios.a`\nAs for physical device build, this library will be compiled statically, and other dependencies must be included manually.\n\n### Building xcframework compatible with both simulators (x64, arm64) and devices\n\n```bash\nmake setup-mac\nmake build-ios-xcframework\n```\nThe xcframework will be under `_builds/ios-xcframework-libpitaya`\nYou can also build openssl xcframeworks using ```make build-openssl-ios-xcframework```\n\n### Building for Windows (should use Developer Powershell for VS 2022)\n\n```bash\nmake build-windows\n```\n\nThe binaries for windows will then be located at `_builds/windows/pitaya-windows.dll` and `_builds/windows/pitaya-windows.lib`.\n\n### Building for Linux\n\n```bash\nmake build-linux\n```\n\nThe binaries for windows will then be located at `_builds/linux/pitaya-linux.so`.\n\n---\n* Note, however, that the chosen options can be changed if you need a different combination. For example, you can easily build statically on linux if you want. Take the Make target as an example.\n\n\n## Tests\n\n# Test requirements\nBuild the mac-tests image\n```bash\nmake build-mac-tests\n```\n\nBuild the binaries for the test Go servers\n```bash\nmake docker-build\n```\n\nStart the test Go servers and their dependencies\n```bash\ndocker compose up\n```\n\nIn order to run the tests, you need [node](https://nodejs.org) installed. Running the tests are done by running the following script in the root folder:\n```bash\n# The tests executable path are always placed alongside the pitaya library.\n./run-tests.py --tests-dir \u003ctests-executable-directory.. e.g. _builds/mac-tests\u003e\n```\n\nYou can also pass command line options, for example:\n```bash\n# Lists all of the tests\n./run-tests.py --tests-dir \u003ctests-executable-directory\u003e --list\n\n# Runs one test by name\n./run-tests.py --tests-dir \u003ctests-executable-directory\u003e /compression/enabled\n\n# Runs one suite of tests\n./run-tests.py --tests-dir \u003ctests-executable-directory\u003e /tls\n```\n\nYou can also run the tests directly through the executable. The problem is that the mock servers will not be started, therefore some tests will fail. You can avoid that by manually starting the servers located in `test/mock-servers` using `./run-tests.py --only-deps`.\n\n## Contribution\nLibpitaya contributions should be done by making a Pull Request from a different branch.\n\n### Native lib contribution\nIn order to run, edit and debug the code, you can generate native projects with CMake. For example, to create an XCode project, you can run the following commands:\n\n```bash\ngit clone https://github.com/topfreegames/libpitaya\ncd libpitaya\ncmake -H. -B_builds/xcode\n# The previous command has created an xcode project inside _builds/xcode.\n# You can build with the command line if you want to:\ncmake --build _builds/xcode --config Release\ncmake --build _builds/xcode --config Debug\n# Or you can open the project with xcode and use it through the IDE\nopen _builds/xcode/pitaya.xcodeproj\n```\nAfter you have edited, and builded the code, you should run the tests and make sure that they pass and also add a test for your specific change. The tests are separated in suites (a suite is a group of related tests). Each suite is located in its own source file under the test directory with names in the format test_\u003csuite-name\u003e.c.  If the addition is related to an existing suite, you can just create the new test and add it to the suite (it is just a function). However, if the functionality belongs in a new suite, you have to create the file and add it to cmake under the following block of code in CMakeLists.txt:\n\n```cmake\nadd_executable(pitaya_tests\n    # Sources\n    test/main.c\n    test/test_compression.c\n    test/test_kick.c\n    test/test_notify.c\n    test/test_pc_client.c\n    #==== Add your file here ====\n    test/test_my_new_suite.c\n    #============================\n    )\n```\n\nHaving added the file, you need to tell test/main.c that there is a new suite to be run, this can be done in the test/main.c source file:\n\n```c\nstatic const int SUITES_START = __LINE__;\nextern const MunitSuite pc_client_suite;\nextern const MunitSuite tcp_suite;\nextern const MunitSuite tls_suite;\nextern const MunitSuite session_suite;\nextern const MunitSuite reconnection_suite;\nextern const MunitSuite compression_suite;\nextern const MunitSuite kick_suite;\nextern const MunitSuite request_suite;\nextern const MunitSuite notify_suite;\nextern const MunitSuite stress_suite;\nextern const MunitSuite protobuf_suite;\nextern const MunitSuite push_suite;\nextern const MunitSuite my_new_suite; // ==\u003e Add your new suite here. Do NOT add new lines\nstatic const int SUITES_END = __LINE__;\n\n...\n\nstatic MunitSuite *\nmake_suites()\n{\n    ...\n\n    suites_array[i++] = pc_client_suite;\n    suites_array[i++] = tcp_suite;\n    suites_array[i++] = tls_suite;\n    suites_array[i++] = session_suite;\n    suites_array[i++] = reconnection_suite;\n    suites_array[i++] = compression_suite;\n    suites_array[i++] = kick_suite;\n    suites_array[i++] = request_suite;\n    suites_array[i++] = notify_suite;\n    suites_array[i++] = stress_suite;\n    suites_array[i++] = protobuf_suite;\n    suites_array[i++] = push_suite;\n    suites_array[i++] = my_new_suite;\n\n    ...\n}\n```\n\nHaving done this, you can now run the tests using the run-tests.py script. If the tests pass, you should open a pull request.\n\n**NOTE**: In most cases, you can just add the changes to the native library and it should be fine. However, if you change the interface of the library, you have to also update the csharp library.\n\n### Using the build-openssl.py script to generate open ssl builds\n\nUse it like the following:\n\n```\n# Android armv7\n\n./build-openssl.py --prefix /tmp/build_dir/android --compile-threads 32 --openssl-tar deps/openssl-1.1.1q.tar.gz android --ndk-dir /home/...path to.../android-ndk-r25b --arch armv7a\n\n# Android aarch64\n\n./build-openssl.py --prefix /tmp/build_dir/android --compile-threads 32 --openssl-tar deps/openssl-1.1.1q.tar.gz android --ndk-dir /home/...path to.../android-ndk-r25b --arch aarch64\n\n# Linux\n\nCC=gcc ./build-openssl.py --prefix /tmp/build_dir/linux --compile-threads 32 --openssl-tar deps/openssl-1.1.1q.tar.gz linux\n\n# Mac and iOS\n\nFor these we use the project at https://github.com/tfgco/OpenSSL\n\n```\n\n### Csharp lib contribution\n\nFor more information, please look in [this](unity/PitayaExample/README.md) document.\n\n## Gotchas for mobile\n\nWhen using libpitaya on mobile, it is important to understand some aspects of its behaviour on Android and iOS.\nA pitaya client will always create a background thread that runs a libuv instance. The behaviour of this thread is different on iOS and Android.\n\n#### iOS\nWhen the application minimizes (goes to background), the pitaya thread will completely stop. This means that it will stop checking for hearbeats and also stop sending heartbeats. It will also stop any kind of pending requests for example. When the app goes back into foreground, the thread will start again. Since the thread stops, the server will stop receiving heartbeats from the client and may disconnect it if the heartbeat timeout passes, so depending on the heartbeat timeout configured by the server, making the app go to background may force the server to disconnect the client.\n\n#### Android\nThe same scenario on Android does not block the thread, but it's quite the opposite. When the app is minimized the thread will continue running even though the app is in background. Since the thread is still sending heartbeats, the connection will not be dropped by the server. This could be a problem since the user might not wish to have the thread still alive while the app is in background.\n\n#### A possible solution\nIf a consistent behaviour for Android and iOS is meant to be achieved, the default behaviour for both platforms will not make this possible. A possible solution is to force a disconnect when the app minimizes regardless of the platform. This disconnection can be triggered instantly or after X amount of seconds, for example. When the app is again in foreground a new connection can be created.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftopfreegames%2Flibpitaya","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftopfreegames%2Flibpitaya","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftopfreegames%2Flibpitaya/lists"}