Rrise
What is Rrise?
Rrise is a Rust binding for Wwise. It is not and does not want to be a complete game engine integration, but rather a starting point for other crates leveraging the binding.
The end goal is to provide game engines written in Rust like Bevy with a safe Wwise API, without having to tinker with the FFI world.
About your expectations...
This is planned to become a rather advanced crate, that paves the way for exciting sound engine work in established Rust game engines. That said, I'm definitely not the most proficient in Rust. If you notice some questionable implementation or architectural choices, please reach out to improve the crate. Pull requests are more than welcome: they are encouraged!
In order to use this crate, you should check the system requirements below.
Capabilities
- Build & run on Windows 10+
- Build & run on WSL1/Linux (on distros where Wwise is supported)
- (AD)PCM, Vorbis & Opus playback
- Initialize/Update/Terminate sound & music engines
- Post simple events (with support for callbacks as functions pointers or closures)
- Set source position
- RTPCs, switches, states and triggers
- Default streaming manager leveraging Wwise's sample streaming manager
- Profiling from the Wwise authoring tool
- Dynamic & static linking of Wwise plugins through cargo features
Logging
Rrise uses the log crate for all its logging needs. Refer to log
's
docs for how to use it.
Wwise project identifiers
Checkout the rrise-headers crate to automatically generate your Wwise project structure as namespaced Rust constants!
Examples
- Minimal example showcasing how to initialize the sound engine, start a moving source and terminate it
- Doppler effect example showcasing RTPCs
- Music engine example with frequency visualizer & event callbacks
Configuration
Config flags
You can set the following cfg
flags through the RUSTFLAGS
environment variable before building to chose which
configuration of Wwise you wish to link against:
Flag | AK_OPTIMIZED |
Comms | Description | |
---|---|---|---|---|
Debug | --cfg wwdebug |
✕ | Useful to debug with AudioKinetic support folks | |
Profile (default) |
--cfg wwprofile (or nothing) |
✕ | ✔ | That's what you should be using during development |
Release | --cfg wwrelease |
✕ | Optimized for final retail builds |
If Comms are disabled, it means you can't connect to the running game from Wwise Authoring app.
For more info, check the AudioKinetic docs.
Wwise Plugins
You can choose to either link statically or dynamically to the Wwise plugins.
Note that some plugins like AkMeter, AkVorbisDecoder and AkOpusDecoder can only be statically linked and are not available for dynamic linking.
See this page for a list of plugins supported by Wwise, per platform.
Dynamic linking
This is the default behavior. Wwise plugins like AkRoomVerb, AkParametricEQ, Motion etc. will be loaded at runtime from their respective shared library as needed.
Any project relying on dynamic linking for some plugins needs to also deploy their respective licensed shared libraries along the final executable (you can do this with a build script for instance).
You can find these shared libraries in $WWISESDK/[platform]/[config]/bin
.
Static linking
You might want to statically link some Wwise plugins instead of loading them at runtime from a shared libary. In this case, you can leverage Rrise's cargo features to enable static linking of such plugins.
For example, if you want to statically link the AkRoomVerb plugin, just build with the AkRoomVerbFX
feature
enabled. When your project runs, you can check that the static version of the plugin was loaded in the debug log:
AkRoomVerbFX has been statically loaded successfully
Note: If you already built your project once, you need to make Rrise's build script rerun to enable static
linking of your features. You can change the value of the RRISE_RERUN_BUILD
environment variable before building to
force a rerun of Rrise's build script. You can also force a full rebuild with cargo clean & cargo build --features=The,Plugin,List
.
Known issues & limitations
- If you dynamically link Wwise effect plugins (default behavior), there is an issue on Windows where if the path given
to
AkInitSettings::with_plugin_dll_path
contains spaces, the DLLs in that folder won't be discoverable by Wwise. - On Linux, when connecting the profiler, you will get those messages in the console (they seem totally harmless):
.../SDK/Linux_x64/Profile/bin/libDefaultConversions.so: cannot open shared object file: No such file or directory
.../SDK/Linux_x64/Profile/bin/libAkSoundEngineDLL.so: cannot open shared object file: No such file or directory
Requirements
- Rust nightly 1.61+ (to support -wholearchive)
- Tested on nightly 1.65.0
- The
bindgen
crate requirements - A licensed (free, trial, commercial,...) version of Wwise installed (2021.1.7, untested on others)
- Wwise itself
- Wwise SDK (C++)
- On Windows:
MSVC
2- Windows 10 SDK
- Build tools (same as Rust, for the
cc
crate) cl.exe
must be in the PATH3- Wwise support for any Visual Studio 20XX deployment platform
- Make sure the
WWISESDK
environment variable is set to the SDK folder of your Wwise installation
- On Linux:
clang
g++
(forlibstdc++
)- Copy the SDK folder from a Windows4 install of Wwise on your Linux workstation (for instance in /opt/wwise)
- Make sure the
WWISESDK
environment variable is set to that folder
- Make sure the
Short-term roadmap
- Spatial module basic API and example
- Review/Improve architecture
Legal stuff
Wwise and the Wwise logo are trademarks of Audiokinetic Inc., registered in the U.S. and other countries.
This project is in no way affiliated to Audiokinetic.
You still need a licensed version of Wwise installed to compile and run this project. You need a valid Wwise license to distribute any project based on this crate.
Footnotes
-
WSL2 on Windows 11 is required to run the
bevy_music_visualizer
example ↩ -
Not tested on other compilers like MinGW or Clang ↩
-
Current limitation of the build script. I want to improve MSVC path discovery in the future to remove this requirement. ↩
-
Audiokinetic doesn't provide direct downloads to their SDK: you can only install it through their launcher. However, this launcher being only available on Windows and MacOS, you'll need to install it on a VM or similar before you can work with this crate on Linux. ↩