{"id":22614008,"url":"https://github.com/salzian/bevy_fmod","last_synced_at":"2025-04-04T21:06:34.153Z","repository":{"id":142502234,"uuid":"610531463","full_name":"Salzian/bevy_fmod","owner":"Salzian","description":"Idiomatic integration of the FMOD audio engine into Bevy projects. Enables spatial audio, real-time parameter adjustments, live updates, and Doppler effects.","archived":false,"fork":false,"pushed_at":"2024-12-04T13:05:30.000Z","size":129,"stargazers_count":66,"open_issues_count":10,"forks_count":6,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-04-04T08:52:08.782Z","etag":null,"topics":["bevy","bevy-audio","bevy-engine","fmod","fmod-api","fmod-library","fmod-studio","game-development","rust","rust-library"],"latest_commit_sha":null,"homepage":"","language":"Rust","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/Salzian.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE-APACHE","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":"2023-03-07T00:39:44.000Z","updated_at":"2025-03-22T12:59:08.000Z","dependencies_parsed_at":"2023-09-26T15:43:44.636Z","dependency_job_id":"ce6780b6-2f70-4299-8a7b-6f3d95c75013","html_url":"https://github.com/Salzian/bevy_fmod","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Salzian%2Fbevy_fmod","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Salzian%2Fbevy_fmod/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Salzian%2Fbevy_fmod/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Salzian%2Fbevy_fmod/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Salzian","download_url":"https://codeload.github.com/Salzian/bevy_fmod/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247249524,"owners_count":20908212,"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":["bevy","bevy-audio","bevy-engine","fmod","fmod-api","fmod-library","fmod-studio","game-development","rust","rust-library"],"created_at":"2024-12-08T18:06:45.144Z","updated_at":"2025-04-04T21:06:34.137Z","avatar_url":"https://github.com/Salzian.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# bevy_fmod\n\n[![Latest compatible Bevy version](https://img.shields.io/badge/Bevy-0.14.2-232326)](https://crates.io/crates/bevy/0.14.2)\n[![bevy_fmod on crates.io](https://img.shields.io/crates/v/bevy_fmod)](https://crates.io/crates/bevy_fmod)\n\nThis crate aims to provide an idiomatic [Bevy] plugin for FMOD. This crate\nwraps [`libfmod`][libfmod].\n\n```shell\ncargo add bevy_fmod\n```\n\n## FMOD\n\nFMOD is a cross-platform audio engine that is\nused [in many games](https://www.fmod.com/games). It is a commercial product,\nwith a free license available [for specific terms][FMOD licensing].\n\n### FMOD attribution\n\nThis crate is not affiliated with FMOD in any way. It is not endorsed by or\naffiliated with Firelight Technologies Pty, Ltd. To use FMOD in your\napplication, you are required to include attribution by Firelight Technologies'\nterms. Learn more [here][FMOD attribution].\n\n## Supported platforms\n\nCurrently, this crate is only tested and developed for Windows (non-UWP) and\nLinux. More platforms are planned eventually.\n\nWeb: \u003chttps://github.com/Salzian/bevy_fmod/issues/51\u003e\n\nPull requests are welcome.\n\n## Linking the FMOD library\n\nDue to FMOD's licensing, this crate does not include the required FMOD\nlibraries. You will need to download the appropriate\nlibraries [here][FMOD libraries download]. This requires a free FMOD account.\n\n### Windows\n\nThe linking process on Windows is straight forward. Download and install the\n\"FMOD Engine\" for Windows. When installing, a folder will be created with FMOD\nlibraries. Copy the following files into root of your project:\n\n- `api/core/lib/x64/fmod.dll`\n- `api/studio/lib/x64/fmodstudio.dll`\n\nWhen publishing your game, you will need to include these libraries in the same\ndirectory as the executable.\n\n\u003e [!CAUTION]\n\u003e\n\u003e The `libfmod` crate requires you to suffix the libraries with `_vc` like this:\n\u003e\n\u003e - `fmod_vc.dll`\n\u003e - `fmodstudio_vc.dll`\n\u003e\n\u003e This is only necessary for Windows. I don't know the background of this\n\u003e requirement, but it was too little of a problem to investigate further.\n\u003e\n\u003e For the nerds that want to dive deeper, this behavior is defined in the crates\n\u003e [build.rs](https://github.com/lebedec/libfmod/blob/8974d07e7c34aa6c94fc598d491931471d6d1799/libfmod/build.rs)\n\u003e file.\n\nThe final game will ship with the following structure:\n\n```\nMy Game/\n├── My Game.exe\n├── fmod_vc.dll\n└── fmodstudio_vc.dll\n```\n\n### MacOS\n\n- Download \"FMOD Engine\" for MacOS.\n- In the dmg file, open the `FMOD Programmers API` folder.\n- You will need these files:\n    - `api/core/lib/libfmod.dylib`\n  - `api/studio/lib/libfmodstudio.dylib`\n\nLinking on MacOS is a bit different to Windows, as the defaults of the OS are\nnot as straight forward as Windows. Also, Windows seems to take parent\ndirectories into account. During development, it is sufficient to put the\nlibraries in the root of your project. When building, the built executable is\ncontained in the `target/debug` directory. Now on Windows, this doesn't seem to\nbe a problem, but on MacOS, the executable is unable to find the libraries.\n\nTo fix this, you have to pass some flags to cargo during development. Have a\nlook at this `.cargo/config.toml`:\n\n```toml\n[target.aarch64-apple-darwin]\nrustflags = [\n    \"-L\", \"native=./vendor/fmod\",\n    \"-C\", \"link-arg=-Wl,-rpath,./vendor/fmod\",\n]\n```\n\nThe first line tells cargo where to look for libraries during development. If\nyou keep the libraries in the root of your project, there is no problem when\nbuilding the project. However, when running the executable, it will not find the\nlibraries, as the executable is in the `target/debug` directory.\n\nI recommend putting the libraries in a known folder like `vendor/fmod` and then\npass the path to cargo using the\n`-L` flag. There are different ways to do this, but using the\n`.cargo/config.toml` is the most convenient to me.\n\nThe second line will determine the rpath of the executable. This is the path\nwhere the executable will look for the libraries. By default, executables will\nlook in a variety of places, including the directory the executable is in. This\nis fine when publishing the game, as you can just use the Windows method and put\nthe libraries in the same directory as the executable. However, during\ndevelopment, the executable is in the `target/debug` directory, which gets\ngenerated automatically by cargo and does not contain the libraries. The\n`\"-C\", \"link-arg=-Wl,-rpath,./vendor/macos\"` flag will tell the executable to\nlook in the `vendor/fmod` directory of your project for the libraries.\n\nBy the end, your project structure should look like this:\n\n```\nmy_game/\n├── .cargo/\n│   └── config.toml\n├── src/\n│   └── \u003csource files\u003e\n├── vendor/\n│   ├── fmod/\n│   │   ├── libfmod.dylib\n│   │   ├── libfmodL.dylib\n│   │   ├── libfmodstudio.dylib\n│   │   └── libfmodstudioL.dylib\n│   └── \u003cother external libraries\u003e\n└── Cargo.toml\n```\n\n### Linux\n\n\u003e [!WARNING]\n\u003e This section might be outdated. The approach described here does work, but\n\u003e does not align with what is described in the [Windows](#windows)\n\u003e and [MacOS](#macos) sections.\n\nBelow are the steps for a fairly minimal method to link the libraries. See the\ncomments in [build.rs](https://github.com/Salzian/bevy_fmod/blob/main/build.rs)\nfor more information.\n\n- Download the \"FMOD Studio\" and \"FMOD Engine\" package for Linux.\n- Create a new folder `fmod` in the root of your project.\n- Extract the `api` folder into it.\n- Copy the contents of [build.rs](https://github.com/Salzian/bevy_fmod/blob/main/build.rs) into your own build script.\n\n## Examples\n\nTo test the examples of this library, clone the repository. FMOD Studio comes\nwith an Examples project. Open it and select `File \u003e Save as...`. Save the\nproject as `\u003cbevy_fmod\u003e\\assets\\audio\\demo_project.fspro`. Now, build the\nproject (\n`File \u003e Build`). This will create a folder called\n`.\\assets\\audio\\demo_project\\Build` which is used by our examples.\n\nRun examples with `cargo run --example \u003cexample_name\u003e`. Find the list of\nexamples in the [Cargo.toml](./Cargo.toml) See the source code of the examples\nfor more details.\n\n## Live Update\n\nLive update is a way of connecting FMOD Studio to your game as it runs, allowing\nyou to update and monitor audio content in real\ntime. [Read more about it here](https://www.fmod.com/docs/2.02/studio/editing-during-live-update.html).\n\nTo enable live update, you need to enable the `live-update` feature. While you\ncan do so in Cargo.toml, we recommend to explicitly enable it with the\n`--features` flag. This way, you won't accidentally include it in your release\nbuilds.\n\n```sh\ncargo run --example minimal --features live-update\n```\n\n[Bevy]: https://bevyengine.org\n\n[FMOD licensing]: https://fmod.com/licensing\n\n[FMOD attribution]: https://fmod.com/attribution\n\n[FMOD libraries download]: https://fmod.com/download#fmodengine\n\n[FMOD revision history]: https://www.fmod.com/docs/2.02/studio/welcome-to-fmod-studio-revision-history.html\n\n[FMOD 2.02.12 img]: https://img.shields.io/badge/FMOD-2.02.12-black\n\n[FMOD 2.02.20 img]: https://img.shields.io/badge/FMOD-2.02.20-black\n\n[libfmod]: https://github.com/lebedec/libfmod\n\n[demo_project]: https://drive.google.com/file/d/13Mxq_jEHXDLuam6M9whNowGUf_KBGKTU/view?usp=sharing\n\n[salzian]: https://salzian.dev\n\n[License img]: https://img.shields.io/badge/License-MIT%20OR%20Apache%202.0-informal\n\n[GitHub releases]: https://github.com/Salzian/bevy_fmod/releases/latest\n\n[GitHub release img]: https://img.shields.io/github/v/release/Salzian/bevy_fmod?filter=v*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsalzian%2Fbevy_fmod","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsalzian%2Fbevy_fmod","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsalzian%2Fbevy_fmod/lists"}