Examples
Sample scripts using the API are installed with GameSynth 2023.1 and higher (in C:\Program Files (x86)\Tsugi\GameSynth\Tool\API, if you haven’t changed the installation folder). They allow you to control GameSynth remotely from Unity, Reaper, Pure Data, etc…
These examples are primarily aimed at showcasing the possibilities of the API. Feel free to improve them and to adapt them to your project’s needs. Join our community on Discord to discuss the API’s usage and the integrations available.
Standalone Apps
GameSynth API Tester
The GameSynthAPITester is a console application that allows for the test of all the commands of the GameSynth API simply by typing them. The communication settings (port, encoding, and delimiting character) are directly read from the GameSynth preferences in the registry, so as long as GameSynth is already running, it is possible to immediately test the API without having to configure anything.
If you are working on an integration between the GameSynth API and a third-party software and are experiencing some issues, the first thing to do is to test the same commands in the GameSynthAPITester application and see if they work, and if not, what error messages are returned.
MetaPlanes
MetaPlanes is a standalone application offering 4 planes on which you can move your mouse to control the meta-parameters of the current patch in GameSynth.
Based on the mode selected for each plane, various ways to map the meta-parameters to the mouse movements are available: using the position of the mouse, its angle and distance from the center of the plane, its speed, its distance from the plane’s corners, etc.
MetaPlanes is especially useful to control ambient patches or musical layers over time.
Functions showcased: get_metanames, set_metavalue, play, stop
Unity scripts
Unity is a popular game middleware, used both by AAA game studios and indie developers. A package is provided - GameSynthAPIExamples.unitypackage - which contains C# scripts adding commands to the Windows menu of Unity. These commands allow for the import of assets from GameSynth without having to leave the editor.
GSAPI_RenderCurrentPatch
This command renders the patch currently selected in GameSynth as a wave file and adds it as an Audio Clip to the project’s Assets folder.
If the patch includes random ranges, it is possible to set a variation percentage and generate several wave files and Audio Clips automatically.
The bit depth and number of channels with which the files are rendered can also be specified.
Functions showcased: get_patchname, is_infinite, set_variation, render_patch
GSAPI_RenderRepositoryPatch
This command can render any patch from the GameSynth repository as a wave file, and make it available as an Audio Clip in the Assets folder of the project.
It is possible to search for the right patch in the repository by entering a text. Checkboxes determine if the text will be searched for in the names of the patches, categories and/or tags.
The list of matching patches is displayed and clicking on one will open it in GameSynth. It is possible to play the patch directly from Unity to see if it fits the requirements. The selected patch can then be rendered as a single file or many variations. The rendering options are similar to the previous command.
Functions showcased: query_patchnames, query_patch, play, stop, is_infinite, set_variation, render_patch
GSAPI_ExportAnimationCurve
This command makes it possible to export an animation curve from the selected game object to the current patch in GameSynth, where it will appear as an automation curve.
Note: in Unity’s Animation panel, please make sure that your animation curve uses the “Euler Angles” interpolation before exporting it.
Functions showcased: get_patchname, set_curvevalue
Reaper scripts
Reaper is digital audio workstation (DAW) widely used in the game audio industry. Examples of Reaper scripts written in the EEL2 language are installed with GameSynth. They do not require any special extension or scripting language to be downloaded and installed. The code can be displayed and it is commented, which makes it a good resource for pedagogical purposes.
GSAPI_RenderCurrentPatch.eel
After selecting the name, bit depth, number of channels, and sound variations desired, this script lets you render the patch currently selected in GameSynth as a wave file and insert it at the position of the cursor in Reaper.
If the patch is infinite, the duration of the wave file will have to be specified. When there is a time selection in Reaper, it is also possible to generate audio that exactly matches that selection.
Functions showcased: get_patchname, get_modelname, render_patch, is_infinite
GSAPI_RenderRepositoryPatch.eel
This script allows the user to enter a text to search patches in the GameSynth repository (e.g., “impact”). It is possible to select if the text should be searched in the names of the patches, in their categories, and / or in their tags.
The user can then enter the number corresponding to one of the patches returned to load it in GameSynth. Once it is done, the GSAPI_RenderCurrentPatch.eel script is called to render the patch at the cursor position in Reaper.
Functions showcased: query_patchnames, query_patch
GSAPI_AutomationExport.eel
This script will export all the selected automation items in a Reaper project as automation curves in GameSynth.
Functions showcased: set_curvevalue
GSAPI_RenderVariationsAtMarkers.eel
This script renders a variation of the current patch at each marker’s position in the Reaper project.
The user can specify the base name for the wave files that will be generated (they will be suffixed by the marker’s index), their bit-depth and number of channels, as well as the amount of variation to use.
Functions showcased: get_patchname, get_modelname, get_variation, set_variation, is_infinite, render_patch
Note: in case you want to launch these scripts directly from one of Reaper’s toolbars, custom icons are located in the API’s Reaper\toolbar_icons subfolder. To use them, simply copy the subfolder into \AppData\Roaming\REAPER\Data\. They will automatically show up in the Reaper’s toolbar icons browser.
Blender add-ons
Blender is a very popular, open-source 3D creation suite. Any aspect of it can be extended by add-ons programmed in Python. The GameSynth Tool API comes with an add-on package containing 2 add-ons. It can be installed like any other add-on in Blender. Go to Edit->Preferences, select Add-ons, and click on the “Install” button. In the browser, select the GameSynth AddOns.zip package, and click on the “Install Add-on” button. The add-ons contained in the package will be installed. You can find them by typing GameSynth in the search box. Make sure to check the box in front of their names to activate them.
GSAPI_RenderCurrentPatch.py
This add-on is accessible in the Sequencer view of the Video Sequencer. In the “Add” menu, select “GameSynth Patch” to render a sound variation of the current GameSynth patch at each selected marker’s position. If no marker is selected, a single sound is rendered at the playback cursor’s location. A settings window lets you specify the folder in which the audio files will be rendered, their bit depth, whether they are mono or stereo, as well as the destination channel in the Sequencer. If the patch is infinite, the duration of the files to be rendered can also be chosen.
Functions showcased: get_patchname, render_patch, is_infinite, window_parameters
GSAPI_ExportCurve.py
This add-on is accessible via the F-Curve context menu of the Graph Editor. At the bottom of the menu, select “Export to GameSynth” to export the first selected F-Curve as an automation curve in the current patch. This allows for the generation of sounds that perfectly match a 3D animation. A dialog box offers to select the target curve, its duration (by default that of the F-Curve in Blender), whether it is looping or not, and various pre-processing options to map the curve data to the useful range in GameSynth.
Functions showcased: get_patchname, get_curvenames, set_curvevalue, window_parameters
Pure Data patches
Pure Data is a free patching environment for audio synthesis and processing. Examples of Pure Data patches using the GameSynth API are installed with GameSynth. They do not rely on any external objects and only requires the vanilla version of Pure Data to be installed.
Note: the netsend object used by PureData to send data via TCP requires the encoding to be set to ASCII and the delimiter code to be set to 59 in the GameSynth API settings.
GSAPI_MetaParametersControl.pd
This patch makes it possible to play and control the current GameSynth patch directly from Pure Data. Sliders are used to adjust the values of the meta-parameters in the GameSynth patch.
It is also possible to replace the current GameSynth patch by loading a new one from the repository without leaving Pure Data.
You can of course expand the Pure Data patch with its own sound generators and logic.
Functions showcased: play, stop, set_metavalue, query_patch
GSAPI_ReceiveEvents.pd
This patch allows you to enable the notifications when events are triggered by GameSynth. When the Pure Data patch receives one of these events, it plays a simple pad sound. The pitch of the synthesizer changes in accordance to the event received.
A companion GameSynth patch is provided, which plays a sequence of sounds in tune with the ones generated by the Pure Data patch.
Functions showcased: play, stop, enable_events
Processing Sketch
Processing is a language - based on Java - that is widely used for creative coding. Processing programs are saved as sketches, and their extension is .pde. A sample sketch is provided with the GameSynth API. Simply open the corresponding .pde file in the Processing IDE, and run it. This sketch has been written with Processing 4.2.
GSAPI_MetaParametersControl.pde
This sketch displays graphics that are modified when the user moves the mouse. The mouse position is also used to control the sound generated by a GameSynth patch in real-time, by sending new values to its meta-parameters.
Functions showcased: load_patch, play, stop, set_metavalue
ADX2 Script
ADX2 is a popular game audio middleware. Its authoring tool, Atom Craft, allows for the creation of interactive audio assets by using an intuitive, DAW-like user interface. It includes the Robot API, with which users can write Python scripts to automate their workflow.
GSAPI_RenderCurrentPatch.py
This script renders one or more variations of the current patch, and registers them as Materials in the Atom Craft project. The hierarchy of objects created will depend on what is selected in Atom Craft when the script is run.
Functions showcased: get_patchname, render_patch, is_infinite
Wwise script
Wwise is a widely adopted game audio middleware. It relies on the Wwise Authoring API (WAAPI) to communicate with other applications. Although many languages can be used, this example script is written in Python and therefore requires the WAAPI client for Python to be installed. The script is executed via a Command Add-on that can be called from Wwise’s context menu. Make sure to extract the archive into the “%APPDATA%\Audiokinetic\Wwise” folder to add the command to the menu.
GSAPI_RenderCurrentPatch.pyw
This script uses the user interface commands of the GameSynth Tool API to display the rendering parameters (bit depth, channels, duration, number of variations and file name). It will then generate one or more sound variations in the selected Container (Actor-Mixer, Random, Sequence or Sound SFX). If the patch is infinite, an additional option will allow for the enabling of the Loop property within the Sound SFX objects, and will set the Loop Start, Loop End and Crossfade Duration to make the sound loop seamlessly.
Functions showcased: get_patchname, render_patch, is_infinite, window_parameters
MAX/MSP Patch
GSAPI_MetaParametersControl.maxpat
This is a community patch provided by Michael Iber. It makes it possible to play and control GameSynth patches from Max/MSP. A patch can be loaded from the GameSynth Repository or locally, like the Electricity.gspatch test file included in the archive. Meta-parameters can be adjusted via individual sliders or by using an XY pad.
A second Max patch named tcp_forwarding.maxpat allows for the control of GameSynth from another computer on the network. These patches rely on objects from the Sadam library to make the TCP connection. Therefore, please install the library via Max/MSP’s Package Manager before using them.
Functions showcased: play, stop, set_metavalue, load_patch, query_patch