{"id":15722638,"url":"https://github.com/dapetcu21/defold-fmod","last_synced_at":"2025-05-07T21:45:15.348Z","repository":{"id":142142910,"uuid":"114560610","full_name":"dapetcu21/defold-fmod","owner":"dapetcu21","description":"FMOD bindings for Defold","archived":false,"fork":false,"pushed_at":"2024-02-27T07:38:20.000Z","size":287833,"stargazers_count":29,"open_issues_count":6,"forks_count":9,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-05-06T10:07:57.039Z","etag":null,"topics":["defold","defold-library"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dapetcu21.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}},"created_at":"2017-12-17T18:53:08.000Z","updated_at":"2025-04-26T00:42:33.000Z","dependencies_parsed_at":"2024-02-27T09:43:43.530Z","dependency_job_id":"601ae299-28ac-4708-83dd-2e81832301d0","html_url":"https://github.com/dapetcu21/defold-fmod","commit_stats":null,"previous_names":[],"tags_count":22,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dapetcu21%2Fdefold-fmod","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dapetcu21%2Fdefold-fmod/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dapetcu21%2Fdefold-fmod/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dapetcu21%2Fdefold-fmod/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dapetcu21","download_url":"https://codeload.github.com/dapetcu21/defold-fmod/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252961842,"owners_count":21832190,"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":["defold","defold-library"],"created_at":"2024-10-03T22:08:43.674Z","updated_at":"2025-05-07T21:45:15.325Z","avatar_url":"https://github.com/dapetcu21.png","language":"C","funding_links":[],"categories":["Libraries"],"sub_categories":["Programming Language"],"readme":"![fmod](./docs/fmod_logo.png)\n\n# FMOD extension for Defold\n\n\u003e [FMOD] sound engine bindings for Defold\n\n**Commercial usage of FMOD products may require a separate license directly with\nFirelight Technologies. For details refer to [fmod.com/resources/eula][fmod-license].**\n\n**According to the [FMOD license][fmod-license], you must credit FMOD in your\nproject's documentation, or in an on screen format. The text should include at\nleast the words \"FMOD\" (OR \"FMOD STUDIO\" IF APPLICABLE) AND \"FIRELIGHT TECHNOLOGIES.\"**\n\n[fmod-license]: https://fmod.com/resources/eula\n\n## Installation\n\nGo to the [Releases page](https://github.com/dapetcu21/defold-fmod/releases),\ncopy a dependency URL, then add it to your dependencies in `game.project`.\n\n### Set the speaker mode\n\nThis step is [only required if you use Studio banks][set_software_format].\nTo set the speaker mode, create an `fmod` section in your `game.project`:\n\n```\n[fmod]\nspeaker_mode = stereo\n```\n\nSupported values for `speaker_mode` are: `default`, `raw`, `mono`, `stereo`,\n`quad`, `surround`, `5.1`, `7.1`, `max`.\n\nIf ever needed, you can also set `sample_rate` and `num_raw_speakers` in the same way.\n\nIf you have issues with stutter, you can try adjusting\n`buffer_length` and `num_buffers` from here as well.\n[More details here](https://fmod.com/resources/documentation-api?version=2.0\u0026page=core-api-system.html#system_setdspbuffersize).\n\nIf you need platform-specific overrides for these settings, append one of\n`_macos`, `_windows`, `_linux`, `_android`, `_ios`, `_html5` to the config key\n(eg. `buffer_length_android`).\n\n### Raise the heap size on HTML5\n\nFMOD will hiccup and not play sound on HTML5 (particularily Safari on iOS and macOS)\nif it doesn't have enough memory for your banks and sound buffers, especially if\nloaded with `load_bank_memory()`, which copies them into memory. The exact amount \ndepends from game to game, but for this example to run, it needs a 512MB heap.\n\n```\n[html5]\nheap_size = 512\n```\n\n### Running in the editor\n\nThe game will bundle fine, but in order for FMOD to be available when running\nfrom the editor, an extra step is required.\n\nCopy the `fmod/res` directory from this repo to a directory in your project\nand add the path to that directory to your `game.project`:\n\n```\n[fmod]\nlib_path = path/to/fmod/res\n```\n\n## Usage\n\nStructs and classes are exposed on the `fmod` and `fmod.studio` namespaces. All\nmethod names are converted from `camelCase` to `snake_case`. Methods that\nreturned values through pointer arguments now actually return the values and\nthrow with a Lua error when their result is not `FMOD_OK`.\n\nEnums are exposed on the `fmod` table without the leading `FMOD_`.\n(eg.: `FMOD_STUDIO_PLAYBACK_PLAYING` is exposed as `fmod.STUDIO_PLAYBACK_PLAYING`)\n\nA fully initialised instance of `FMOD::Studio::System` is exposed to Lua as\n`fmod.studio.system` and the corresponding instance of\n`FMOD::System` (the low level system), is exposed as `fmod.system`.\n\nYou can use `vmath.vector3` instead of FMOD's `FMOD_VECTOR` struct. Conversion\nis being done seamlessly.\n\nSee an [example script][example] to get an idea.\n\nRefer to the [FMOD API Documentation] for details about the available APIs.\n\nHere's some sample code:\n\n```lua\nfmod.studio.system:load_bank_memory(resource.load(\"/banks/Master Bank.bank\"), fmod.STUDIO_LOAD_BANK_NORMAL)\nfmod.studio.system:load_bank_memory(resource.load(\"/banks/Master Bank.strings.bank\"), fmod.STUDIO_LOAD_BANK_NORMAL)\nfmod.studio.system:load_bank_memory(resource.load(\"/banks/Vehicles.bank\"), fmod.STUDIO_LOAD_BANK_NORMAL)\n\nlocal event_description = fmod.studio.system:get_event(\"event:/Vehicles/Basic Engine\")\nlocal event = event_description:create_instance()\nevent:start()\n```\n\n## Memory management\n\nInstances of `FMOD_STUDIO_EVENTINSTANCE` are automatically garbage collected by\nLua and `release()` is called automatically for you when you no longer hold\nreferences.\n\n**Any other class is not memory managed and you still need to call `instance:release()`\nmanually, where applicable.**\n\n## Error handling\n\nYou can retrieve the error code of an FMOD error and use it for more specific\nerror handling:\n\n```lua\nlocal ok, err = pcall(function ()\n  return fmod.studio.system:get_event(\"event:/Inexistent event\")\nend)\nif ok then\n  local event_description = err\n  event_description:create_instance():start()\nelse\n  print(err) -- The error is a string\n  local code = fmod.error_code[err] -- The FMOD error code (a number).\n  print(code)\n  if code == fmod.ERR_EVENT_NOTFOUND then\n    print(\"Ooops! This event doesn't exist!\")\n  end\nend\n```\n\n## 64-bit values\n\nA small amount of FMOD functions and structs work with 64-bit number types.\nLua 5.1 doesn't have a 64-bit type. Functions with 64-bit arguments accept\nregular lua numbers instead if the extra precision is not needed, but if you\nneed more, use `fmod.s64()` and `fmod.u64()`,\n\nFunctions that return 64-bit numbers will return instances of `fmod.s64` or `fmod.u64`.\n\n```lua\nx = fmod.s64(num) -- Converts a Lua number (up to 52 bits of integer precision) to a 64-bit value\nx = fmod.s64(low, high) -- Creates a 64-bit value from two 32-bit integers\nx.value -- Does the best-effort conversion to a Lua number (accurate within 52 bits of precision)\nx.low -- Gets the lowest 32-bits as an unsigned int value\nx.high -- Gets the lowest 32-bits as an unsigned int value\ntostring(x) -- Converts the value to a numeric string\n```\n\n## Studio Live Update\n\nAdd the following setting to your `game.project` to enable the live update server\nused by FMOD Studio.\n\n```\n[fmod]\nlive_update = 1\n```\n\n## Loading banks from the file system\n\nFor development it's ok to put your banks in `custom_resources` and use\n`load_bank_memory` to load them, but this is inefficient (costs a lot of memory\nand you don't benefit from streaming).\n\nWhen building, you want your banks on the file system. In your\n`bundled_resources` directory, add the banks to the following paths:\n\n* For Windows, Linux and iOS: `win32/banks/`, `linux/banks/`, `ios/banks/`\n* For macOS: `osx/Contents/Resources/banks`\n* For Android: `android/assets/banks`\n\nThen, from your game code:\n\n```lua\nlocal bundle_path = sys.get_application_path() -- The path to your game's directory\nlocal path_to_banks = bundle_path .. \"/banks\"\nlocal system_name = sys.get_sys_info().system_name\nif system_name == \"Darwin\" then\n  path_to_banks = bundle_path .. \"/Contents/Resources/banks\"\nelseif system_name == \"Android\" then\n  path_to_banks = \"file:///android_asset/banks\"\nend\nfmod.studio.system:load_bank_file(path_to_banks .. \"/Master Bank.bank\", fmod.STUDIO_LOAD_BANK_NORMAL)\n```\n\n**Warning: Don't use relative paths for loading banks. Use `sys.get_application_path()`. Relying on the current working directory being the same as the game's installation directory is not always correct (especially on platforms like macOS and iOS).**\n\n## Sound while the game is minimised\n\nBy default, FMOD should respect the setting of `engine.run_while_iconified`. This\nmeans that if the engine can run in the background, FMOD will too, otherwise\nall audio will be paused while the engine is minimised (and paused as well).\n\nIf you'd like to keep the engine running in the background but still pause the music,\nset `engine.run_while_iconified = 1` and add a new setting `fmod.run_while_iconified = 0`.\n\n## Nintendo Switch support\nAfter [getting access to Defold for Nintendo Switch](https://defold.com/manuals/nintendo-switch/), \nfollow [these instructions](https://forum.defold.com/t/fmod-extension-for-switch/65719).\n\n## Contributing\n\nSee [CONTRIBUTE.md](./CONTRIBUTE.md) for details about how to contribute to this project.\n\n[example]: ./main/main.script\n[FMOD]: https://fmod.com\n[FMOD API Documentation]: https://www.fmod.com/resources/documentation-api?version=2.0\u0026page=content/generated/studio_api.html\n[bundle_resources]: https://www.defold.com/manuals/project-settings/#_project\n[set_software_format]: https://www.fmod.org/docs/content/generated/FMOD_System_SetSoftwareFormat.html\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdapetcu21%2Fdefold-fmod","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdapetcu21%2Fdefold-fmod","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdapetcu21%2Fdefold-fmod/lists"}