Audio Kata Development

Initial Setup

• Clone this repository
• Install Unity Hub and Unity Editor version 6000.0.25f1 (as of 1/17/2025)
• Open the project. If it is broken, it's likely due to FMOD - open in Safe Mode and do the below FMOD setup.
• Set up FMOD (see below)

FMOD Setup

We are using FMOD as our main audio library. The FMOD license does not allow distributing their library in open source repositories (see https://qa.fmod.com/t/how-to-handle-fmod-in-an-open-source-project/21208/2).

So, additional setup is required when initially loading the project.

Download/Import

• Go here: https://www.fmod.com/download#fmodforunity
• Download FMOD for Unity (will be a .unitypackage file)
  • As of this writing, version 2.02.25 is being used. You may need to hit Older and select it from the dropdown. Make sure it is Unity Verified!

• Open the AudioKata project in Unity
• In the toolbar at the top, go to Assets -> Import Package -> Custom Package

• Select the package file you downloaded and Import everything

After importing, it will open up a new FMOD setup window. I'd advise hitting the checkbox that prevents it from opening every time the project opens.

FMOD Setup
The following is laid out as "the section on the left" -> "what to do in that section".

Welcome -> Start
Updating -> Next
Linking -> FMOD Project, navigate to AudioKata/fmod/audiokata and select audiokata.fspro
Listener -> Should already be handled. If there are any that need migrating, do the replacement. If it doesn't move all of them, ignore it and go Next.
Unity Audio -> Should already be disabled. Hit Next Unity Sources -> IGNORE THIS! There will only be Unity sources on prefabs used for Unity audio, not FMOD audio. Hit Next Source Control -> Should already be taken care of. Next.

Final Touches
Now, in the Unity project go to AudioKata->Setup at the top and check "Enable FMOD" to compile FMOD-dependent classes. If this is done before FMOD is set up there are compile errors and it'll yell about needing to open in Safe Mode when opening the project. So, best to do things in order ;)

Test
Time to test. Go to AudioKata->Bootstrap in the toolbar at the top to open up the editor play window, and run the game flatscreen or vr. Choose a song, and you can fire guns with Q and E. Right click + drag to move the camera. You should hear audio when firing the guns and hitting targets!

Final Customization

Add any additional custom models etc. to the Customization directory. The directory is created on first run and defaults are copied there.

PC location: <build directory>/Customization

Android/Quest location: /sdcard/Android/data/com.octo.AudioKata/files/Customization

Building

You can build for "Windows/Mac/Linux" for development. If you build to a directory named "Build" or "build" it will be ignored by git.

If installing on a Quest you can build for "Android".

Scenes Overview

You can use the bootstrap menu in AudioKata/Bootstrap to load scenes. The scenes are as follows:

AudioKata.Bootstrap - starting scene, loads initial assets before main scene loads

AudioKata.Main - main scene, contains all UI/gameplay as of June 2023. Different "Pages" are opened/closed to change views.

AudioKataTests.DebugSphere - debug scene, not built by default. Useful for testing gameplay and rendering changes. The "DebugSphere" object can be used to control song playback. Selecting the "Play" checkbox within it starts/stops the map playing. You can fire the guns with Q/E and move the camera while holding right mouse button.

AudioKataTests.UI.Debug - debug scene, not built by default. Useful for testing UI changes. You can click buttons with left mouse button. Note - as of June 2023, if the Oculus runtime is selected instead of Open XR, the inputs may be offset or have a seemingly different origin for the raycast. Switch to Open XR to fix.

Development Guidelines

These are not set in stone, but they are the general approach to developing within this project.

• UI changes are done using Prefabs as much as possible. This reduces the amount of scene modifications that happen and makes changes easier to track within git.
• Do things async when possible. Don't hog the main thread.
• Async operations should use UniTask

As more are determined they can be added here.

Custom Sound Packs

AudioKata supports loading in sound files at runtime for the various hit sounds/gun sounds in the game.

Creating a Sound Pack

1. Create a folder with a unique name identifying this sound pack.
2. Create custom hit sounds as .wav files and place them in this folder. They can be in subdirectories if desired.

Note - Hitsounds cannot exceed 1 second in duration, or they may be cut short! This is due to how we handle pooling. See MaxHitSoundDurationSec in AudioSystem.cs.

3. In the root of this folder, create an info.json file with the following fields:

"name" - This is the user-readable name for the sound pack, as seen in UI for selecting packs (TODO)
"description" - This is a human-readable description of this sound pack.
"author" - Who made this sound pack? This is just a string, so you can include multiple people if needed.
"velocities" - This is the array of velocity data, the main piece of this file. If you don't include one of the below velocities then the default hitsound will be used.

Each object in "velocities" has the following:

"velocity" - This is the velocity (or sound identifier) indicating which hit/gun sound this refers to. See below table for reference (taken from AudioConstants.cs).

ChainStart - 1
ChainNode - 2
Melee - 3
Kick - 20
Percussion - 60
Snare - 127
Silent - 999
GunFireHit - 1001
GunFireMiss - 1002

"isSpatialized" - This is either true or false. If true, plays the sound with 3D spatialization (this is probably what you want).

"filePath" - This is the path to the .wav file that should play when this hit sound is triggered. The path is relative to this file. For example, if you had the following directory structure:

test_hitsounds/  
    info.json
    targets/
        melee.wav
    gun_hit.wav

Then the filePath you'd want for the melee velocity (3) would be "targets/melee.wav", and the filePath you'd use for gun hits (velocity 1001) would be "gun_hit.wav".

Full example info.json:

{
	"name": "Test Hitsounds",
	"description": "A test hitsound pack, with file names describing what the velocities are for.",
	"author": "bookdude13",
	"velocities": [
		{
			"velocity" : 1,
			"isSpatialized" : true,
			"filePath": "chain_start.wav"
		},
		{
			"velocity" : 2,
			"isSpatialized" : true,
			"filePath": "chain_node.wav"
		},
		{
			"velocity" : 3,
			"isSpatialized" : true,
			"filePath": "melee.wav"
		},
		{
			"velocity" : 20,
			"isSpatialized" : true,
			"filePath": "kick.wav"
		},
		{
			"velocity" : 60,
			"isSpatialized" : true,
			"filePath": "percussion.wav"
		},
		{
			"velocity" : 127,
			"isSpatialized" : true,
			"filePath": "snare.wav"
		},
		{
			"velocity" : 1001,
			"isSpatialized" : true,
			"filePath": "gun_hit.wav"
		},
		{
			"velocity" : 1002,
			"isSpatialized" : true,
			"filePath": "gun_miss.wav"
		}
   ]
}

Sharing Sound Packs

• Zip up the folder and post in the Discord
• Users will unzip and put the folder in AudioKata/Sounds. If that folder doesn't exist yet, create it.
  (on Quest standalone the folder is sdcard/Android/data/com.octo.AudioKata/Sounds instead)
  Make sure that the extracted folder isn't nested, i.e. that the structure ends up as AudioKata/Sounds/{soundpack_name}/info.json, and not AudioKata/Sounds/soundpack_name/soundpack_name/info.json

Tools, Tips & Tricks

• There's a debug menu you can open with F12, class is DebugUI.cs
• Check out the custom Inspector windows in the toolbar under AudioKata
• The AudioKataTests.DebugSphere scene is super helpful for debugging stuff, although it won't play all audio.

Localization

The Unity Localization package is being used. Docs: https://docs.unity3d.com/Packages/com.unity.localization@1.5/manual/QuickStartGuideWithVariants.html#localize-strings

Quick reference:

• Main settings can be found in Project Settings, under Localization
• The tables can be found from Window -> Asset Management -> Localization Tables
• You can make a text component localized by right clicking and selecting Localize at the bottom
• You can change the current locale in both editor and play mode from the Window -> Asset Management -> Localization Scene Controls window, by changing the active locale

Settings

Settings categories are localized within SettingsCategoryUI and the AKSettingsStrings table. Each settings category (in the enum) is expected to have a corresponding entry in the table, with the key being settings_category_{name-lowercase}, i.e. settings_category_gameplay.

Individual settings are localized within SettingsControlsFactory and the AKSettingsStrings table. Each setting is expected to have entries in the table for the name and description.

• The key for the name should be of the form setting_name_{id}, where {id} is the setting id/key used in UserPreferences (i.e. id is targetSpeedMultiplier, full key in the localized string table is setting_name_targetSpeedMultiplier )
• The key for the description should be of the form setting_description_{id}, where {id} is the setting id/key used in UserPreferences (i.e. id is targetSpeedMultiplier, full key in the localized string table is setting_description_targetSpeedMultiplier )

Any added setting that is visible to the user is expected to add these entries to the localization table.