SDK Integration (Unreal)

Estimated reading: 7 minutes 43 views

The SDK integration process involves the following:

Chroma Design
Revisions
Sample Project
Tools
Integration
Testing
Performance
Haptic Design
Modding

Chroma Design

The Chroma Design is the starting point. The team provides 15 sample effects that play on an animated web page. The sample effects correspond to short gameplay video clips and give an idea to the type of animation that could play for a set of game events. The samples are available to use for the specified effect or can be used for any other effect which is completely up to the developer. The developer may ask for effect revisions or additional sample effects. If gameplay video is not available, the developer can provide a description or reference art to conceptualize the desired effect.

Revisions

Some Chroma Designs require revisions to add more requested effects or to make changes through the feedback of reviewing the Chroma Design. Revisions can be requested which result in a subset of alterations from the previous design or add completely new game events. Fill out the Chroma_Sensa_Template_Developers.xlsx Template which provides all the necessary fields for making design requests and revisions.

Sample Project

The developer specifies which game engine is used by the game so that a sample project can be shared with sample code for the specified engine. The sample project will have the same effects that were defined in the Chroma Design and ported to the target language/game engine. The sample project will include a plugin to add the Chroma SDK to the specified game engine, and the ported sample code and sample animations from the Chroma Design.

Tools

The Web Chroma Editor creates Chroma animations and code snippets from several input sources. Designers can create Chroma animations without writing any code. The toolset can use input sources as video, text, camera, web cam, desktop capture, gradients, patterns, images, and blended animations.

The Chroma Design Converter can automatically port a web based Chroma Design to several languages and game engines.
The Synesthesia Console can generate haptic configurations automatically for your Chroma integration.

Integration

The integration process can be as easy as copy and paste from the sample project into the game code. Most likely, it’s a matter of finding game triggers in the game code to find the optimal place to add a call to PlayAnimation(). The typical Chroma integration process lasts 3 – 5 days for a single developer. Haptics integration can take 0 days by using automatic mode. Manually adding haptics can take about the same amount of work as Chroma to add the calls to SetEventName() in the right places. Chroma and haptics are independent meaning sometimes they play together and sometimes they play separately, which is completely up to the designer. In most cases for game engines after the game build completes, the Chroma animations need to be copied to the animation folder within the game’s content folder.

Testing

The team can provide QA on the game build when integration has completed. Steam beta keys and Epic Store beta keys make testing possible before a game launches. This can be a good way to provide design revisions by testing and giving feedback on the build. To support the QA process, it will be important to include a level selector and potentially console commands that make it easy to navigate the build to test the game triggers at the right moments to validate the visuals work as expected. Beta key access is limited to the engineering and QA review team.

Performance

Performance Considerations

Avoid Blocking the Update/Rendering Thread:

Calling the Chroma API in the middle of an update or rendering thread can cause noticeable lag if not handled properly.

Two Approaches for Animation References:

By ID (Synchronous):
- Methods that reference animations by ID are synchronous. These calls can block the thread they run on.
- Recommendation: Use a dedicated thread outside the main update/render thread if you plan to call by ID.
By Name (Asynchronous):
- Methods that reference animations by name have been modified to run in the background and return immediately.
- This design avoids any performance impact on the main thread.
- Recommendation: It is safe to call these methods directly from the main thread since they won’t block it.

SetEventName Details:

SetEventName is asynchronous and rate-limited to 30 FPS.
Using SetEventName to add external Chroma or haptics is generally the best way to maximize performance.

The following chart measures SetEventName calls per second with a unique number of events. The high framerate shows the method will have little performance impact with a large number of simultaneous events.

GetAnimation Behavior:

GetAnimation returns the ID of a loaded animation immediately or sends the operation to open the animation in the background if it’s not already loaded.

Preloading Animations:

If yor design calls for using PlayChromaAnimationName during update or rendering, preload animations during level loading to avoid runtime lag.

Performance is a key concern when adding Chroma and haptics to event triggers. Calling the API in the middle of an update or rendering thread could cause noticable lag if designed incorrectly. Methods that reference animations by id are synchronous and may block the calling thread. Methods that reference animations by name have been modified to pass the operation to the background and return immediately to avoid any performance impact. SetEventName is asynchronous and is rate limited to 30 FPS. GetAnimation will return the id of a loaded animation immediately or send the open animation operation to the background. To maximize performance use SetEventName to add external Chroma and haptics to the game. Preload animations during the level loading stage when using PlayChromaAnimationName if the design calls from the update or rendering thread. Use a dedicated thread outside the update and rendering thread If you plan to reference animations by id.

Asynchronous Methods:

The following methods have been adapted to work in the background (asynchronously) and can be safely called from the main thread without causing performance bottlenecks.

AddNonZeroAllKeysAllFramesName
AddNonZeroAllKeysName
CloseAnimationName
CopyKeyColorName
CopyKeysColorAllFramesName
CopyNonZeroAllKeysAllFramesName
CopyNonZeroAllKeysName
CopyNonZeroTargetAllKeysAllFramesName
CoreStreamBroadcast
CoreStreamBroadcastEnd
CoreStreamGetAuthShortcode
CoreStreamGetFocus
CoreStreamGetId
CoreStreamGetKey
CoreStreamGetStatus
CoreStreamReleaseShortcode
CoreStreamSetFocus
CoreStreamWatch
CoreStreamWatchEnd
DuplicateFirstFrameName
DuplicateFramesName
DuplicateMirrorFramesName
FadeEndFramesName
FadeStartFramesName
FillRandomColorsBlackAndWhiteAllFramesName
FillThresholdColorsAllFramesName
FillThresholdColorsMinMaxAllFramesRGBName
FillThresholdColorsRGBName
FillZeroColorAllFramesRGBName
GetAnimation
InsertDelayName
InvertColorsAllFramesName
MakeBlankFramesName
MakeBlankFramesRGBName
MultiplyColorLerpAllFramesName
MultiplyIntensityAllFramesName
MultiplyIntensityAllFramesRGBName
MultiplyIntensityColorName
MultiplyIntensityName
MultiplyIntensityRGBName
MultiplyTargetColorLerpAllFramesName
OverrideFrameDurationName
PlayChromaAnimationName
PreviewFrameName
ReduceFramesName
ReverseAllFramesName
SetChromaCustomFlagName
SetEventName
SetIdleAnimationName
SetKeyColorAllFramesName
SetKeyColorName
SetKeysColorAllFramesName
SetKeysColorAllFramesRGBName
StopAll
StopAnimationName
StopAnimationType
SubtractNonZeroAllKeysAllFramesName
SubtractNonZeroAllKeysName
TrimEndFramesName
TrimStartFramesName
UseForwardChromaEvents
UseIdleAnimation
UseIdleAnimations

Haptic Design

Just like Chroma Designs, the Haptic Design can be provided by the team. Adding haptic support does not require adding assets to the game. Haptics can be added to a game without code changes and after the game has released. Haptics can be added through creation of a haptic configuration file. Developers can use the Synesthesia Console which automates creation of the haptic configuration file within HapticFolders and will add some mockup haptic files (simple haptic effect which can be edited with Haptic Composer) when event names follow a naming convention. Haptic configuration files are automatically distributed by the team through Chroma App updates.

Modding

The decision to add Chroma mod support for a title is completely up to the developer. If the developer decides to block modding, Chroma animations can be loaded from a byte array which sandboxes and protects against any modifications to the Chroma animation assets. If the developer wants to use modding, Chroma animation assets are placed within the installation directory. Modders can modify the Chroma animations assets that are loaded by the title. The API provides CloseAnimation which reloads the Chroma animation from disk. This allows Chroma animations to be modified externally without needing to relaunch the title. Chroma animation playback also supports relative paths from the content folder. Relative paths can be used to organize several mods within the content folder. The title can have a configuration menu that switches between mod subfolder names which changes the relative path for loading the Chroma animations. The C++ Chroma Mod Sample shows how relative paths can be used to detect and use mods, which is applicable for any game or custom engine.