Interhaptics has an extension for GameMaker, which allows you to add haptic feedback to your GameMaker games.
To create your own haptic effects for use with Interhaptics you can use the Haptic Composer tool, which includes an Audio to Haptic feature to generate a haptic effect from audio.
Note: This extension is only supported on Windows.
This guide shows how to set up the Interhaptics extension for Gamemaker.
Note: Before you can access the GitHub repository with the Interhaptics Game Engine SDK releases you’ll be asked to provide some required information.
Assets, download the Source code (zip) package.GMEXT-Interhaptics/source/interhaptics_sdk.After extracting the SDK contents to the folder, the folder’s contents should look as follows:
Download the latest release of the extension.
In GameMaker, open an existing project or create a new one. Next add the extension to the project.
In the Extension Options, set the Windows SDK to the correct relative folder path: ../interhaptics_sdk/interhaptics_windows.
This chapter covers the basic use of the Interhaptics extension.
The first thing to do is initialising the extension using interhaptics_init.
After that, you should check for the presence of a “provider”, which is an attached device (e.g. a controller) that is capable of providing haptics feedback. To initialise the provider, call interhaptics_providers_init. To check if a provider is present, call interhaptics_providers_available.
/// Create Event
interhaptics_init();
interhaptics_providers_init();
Haptics effects are stored in .haps files, which use a custom file format used by Interhaptics.
You can add a haptics effect stored in a .haps file using interhaptics_add_hm:
var _file = file_text_open_read("HapticMaterials/Body Hit.haps")
var _content = file_text_read_string(_file);
file_text_close(_file);
hm_index = interhaptics_add_hm(_content);
You can then add one or more targets for this haptics effect:
var _commanddata =
{
sign: INTERHAPTICS_OPERATOR.PLUS,
group: INTERHAPTICS_GROUP_ID.PALM,
side: INTERHAPTICS_LATERAL_FLAG.GLOBAL
};
interhaptics_add_target_to_event(hm_index, [_commanddata]);
To update Interhaptics, you should first compute all haptics events, then render the haptics every step:
/// Step Event
var _time = current_time / 1000;
interhaptics_compute_all_events(_time);
interhaptics_providers_render_haptics();
Use interhaptics_play_event to play a haptic effect:
interhaptics_play_event(hm_index, -time, 0, 0);
/// Clean Up Event
interhaptics_providers_clean();
interhaptics_quit();
Interhaptics Docs Section: Engine Control
This module contains the functions related to Engine Control.
This module offers a collection of functions designed to address specific tasks and provide utilities for various purposes. Explore the available functions to make the most of the functionalities provided by this module.
This function initialises the different components and modules of the Interhaptics Engine:
interhaptics_init()
Returns:
Boolean
This function cleans up the different components and modules of the Interhaptics Engine. To be called before the application is quit.
Syntax:
interhaptics_quit()
Returns:
N/A
This function sets the global rendering intensity factor for the whole engine.
Syntax:
interhaptics_set_global_intensity(intensity)
This function gets the global rendering intensity factor for the whole engine.
It returns the global intensity, or -1 if the mixer is not initialised.
Syntax:
interhaptics_get_global_intensity()
Returns:
Real
This function adds the content of an .haps file to the Interhaptics Engine for future use. It returns a reference to the new haptic effect to be used in other functions.
Syntax:
interhaptics_add_hm(content)
| Argument | Type | Description |
|---|---|---|
| content | String | The JSON content of the .haps file to be loaded. This needs to follow the Interhaptics .haps format. |
Returns:
Real
This function creates a haptic effect by processing parameters such as amplitude, pitch, and transients. This function generates a haptic effect based on the given input parameters and can optionally loop it.
It returns the ID of the haptic effect created.
Syntax:
interhaptics_add_parametric_effect(amplitude, pitch, freq_min, freq_max, transient, is_looping)
| Argument | Type | Description |
|---|---|---|
| amplitude | Array of Real | An array of amplitude values. Should be formatted as Time – Value pairs. Value is between 0 and 1. |
| pitch | Array of Real | An array of pitch values. Should be formatted as Time – Value pairs. Value is between 0 and 1. |
| freq_min | Real | The minimum value for the frequency range. |
| freq_max | Real | The maximum value for the frequency range. |
| transient | Array of Real | An array of transient values. The array should be formatted as Time – Amplitude – Pitch triplets, with both Amplitude and Pitch values ranging between 0 and 1. |
| is_looping | Boolean | Indicates whether the effect should loop or not. |
Returns:
Real
This function deletes an existing haptic effect.
Syntax:
interhaptics_delete_hm(material_ref)
This function replaces the content of an already loaded haptic effect and returns whether the replace was successful. This can be useful when the ID of the haptic effect needs to be persistent.
Syntax:
interhaptics_update_hm(material_ref, content)
Interhaptics Docs Section: Engine Events
This module contains the functions related to Engine Events.
This module offers a collection of functions designed to address specific tasks and provide utilities for various purposes. Explore the available functions to make the most of the functionalities provided by this module.
This function starts the rendering playback of a haptic source. Sets the starting time to 0 + different offsets. If the event is already playing, it restarts with the new offets. If the source does not already exist, it will be created.
Syntax:
interhaptics_play_event(material_ref, vibration_offset, texture_offset, stiffness_offset)
This function stops the rendering playback of a haptic source.
Syntax:
interhaptics_stop_event(material_ref)
| Argument | Type | Description |
|---|---|---|
| material_ref | Real | The ID of the source to stop, which is the same as the attached haptic effect. |
Returns:
N/A
This function stops the rendering playback of all haptic sources.
Syntax:
interhaptics_stop_all_events()
Returns:
N/A
This function adds a target within the range of the source. The Interhaptics Engine will remap device endpoints and in-range targets to the device management layer for haptic playback.
Syntax:
interhaptics_add_target_to_event(material_ref, target)
| Argument | Type | Description |
|---|---|---|
| material_ref | Real | The ID of the source to add a target to, which is the same as the attached haptic effect. |
| target | Array of Interhaptics_CommandData | A target contains a group of body parts, lateral flags, and exclusion flags. |
Returns:
N/A
This function adds a target within the range of the source. The Interhaptics Engine will remap device endpoints and in-range targets to the device management layer for haptic playback.
Syntax:
interhaptics_remove_target_from_event(material_ref, target)
| Argument | Type | Description |
|---|---|---|
| material_ref | Real | The ID of the source to add a target to, which is the same as the attached haptic effect. |
| target | Array of Interhaptics_CommandData | An array of Interhaptics_CommandData to build a target. A target contains a group of body parts, lateral flags, and exclusion flags. Only perfectly matching targets will be removed. |
Returns:
N/A
This function removes all targets from a source range. The Interhaptics Engine will remap device endpoints and in-range targets to the device management layer for haptic playback.
Syntax:
interhaptics_remove_all_targets_from_event(material_ref)
| Argument | Type | Description |
|---|---|---|
| material_ref | Real | The ID of the source to remove all targets from, which is the same as the attached haptic effect. |
Returns:
N/A
This function must be called in the application main loop to trigger the rendering of all haptic buffers at a specific time. The Interhaptics Engine will compare the current time with the last known value to build a buffer large enough to cover frame drops. This function can be called from the main thread or in a parallel loop. It must be called at least once before triggering the device update event.
Syntax:
interhaptics_compute_all_events(current_time)
This function updates the spatial positions for a specific source target.
Syntax:
interhaptics_update_event_positions(material_ref, target, texture_position, stiffness_position)
| Argument | Type | Description |
|---|---|---|
| material_ref | Real | The ID of the source, which is the same as the attached haptic effect. |
| target | Array of Interhaptics_CommandData | A vector of Interhaptics_CommandData to build a target. A target contains a group of body parts, lateral flags, and exclusion flags. Only perfectly matching targets will be updated. |
| texture_position | Real | The new texture position. |
| stiffness_position | Real | The new stiffness position. |
Returns:
N/A
This function sets the offsets for a specific haptic source.
Syntax:
interhaptics_set_event_offsets(material_ref, vibration_offset, texture_offset, stiffness_offet)
This function clears all inactive sources from memory. Inactive sources are kept in memory to avoid deletion and creation when playing and stopping a source.
Syntax:
interhaptics_clear_inactive_events()
Returns:
N/A
This function clears all active sources from memory. Deleted sources can be recreated by calling the interhaptics_play_event function.
Syntax:
interhaptics_clear_active_events()
Returns:
N/A
This function clears a specific haptic source, whether it is active or not.
Syntax:
interhaptics_clear_event(material_ref)
| Argument | Type | Description |
|---|---|---|
| material_ref | Real | The ID of the source, which is the same as the attached haptic effect. |
Returns:
N/A
This function sets the haptics intensity factor for a specific source.
Syntax:
interhaptics_set_event_intensity(material_ref, intensity)
This function sets the loop flag for a specific source.
Syntax:
interhaptics_set_event_loop(material_ref, number_of_loops)
This function sets the haptics intensity factor for a specific target of a source.
Syntax:
interhaptics_set_target_intensity(material_ref, target, intensity)
| Argument | Type | Description |
|---|---|---|
| material_ref | Real | The ID of the source, which is the same as the attached haptic effect. |
| target | Array of Interhaptics_CommandData | The target to change intensity. |
| intensity | Real | The intensity factor value. Always clamped above 0. |
Returns:
N/A
Interhaptics Docs Section: Key Concepts
This module contains the functions related to providers.
This module offers a collection of functions designed to address specific tasks and provide utilities for various purposes. Explore the available functions to make the most of the functionalities provided by this module.
This function handles the initialisation process of the specific device’s COM, its haptic settings for rendering and subscription to the Interhaptics Engine. It returns false if the initialisation process fails.
Syntax:
interhaptics_providers_init()
Returns:
Boolean
This function checks the availability of the device before triggering haptic playback. It returns true if the provider is present, false if not.
This optional step can help improve performance.
Syntax:
interhaptics_providers_available()
Returns:
Boolean
This function is responsible for de-initialising the device’s COM, if necessary, and for unsubscribing the provider from the Interhaptics Engine. It returns false if the de-initialisation process fails.
Syntax:
interhaptics_providers_clean()
Returns:
Boolean
API triggers the rendering process for the provider by retrieving the necessary haptic buffers, transcoding them if required, and playing them back on the associated device. This API must be called for all targeted devices. It is mandatory to call interhaptics_compute_all_events from the Interhaptics Engine before calling interhaptics_providers_render_haptics for synchronized haptic rendering. Typically, both APIs are implemented in the same loop, with interhaptics_compute_all_events called before the interhaptics_providers_render_haptics calls.
Syntax:
interhaptics_providers_render_haptics()
Returns:
N/A
Interhaptics Docs Section: Shared Types
This module contains the constants and structs related to shared types.
The following are the constants that the Interhaptics extension defines. All of them are defined as an enum.
The Interhaptics extension also defines a Struct:
Interhaptics Constant INTERHAPTICS_OPERATOR
This enum represents operators used in the haptic body mapping. The possible values are:
| Member | Description |
|---|---|
MINUS | Represents a minus operator (-1) |
NEUTRAL | Represents a neutral operator (0) |
PLUS | Represents a plus operator (1) |
Interhaptics Constant INTERHAPTICS_LATERAL_FLAG
This enum represents the lateral position of a body part. The possible values are:
| Member | Description |
|---|---|
UnknownPosition | Represents an unknown position. (-1) |
GLOBAL | Represents the global position. (0) |
RIGHT | Represents the right position. (1) |
LEFT | Represents the left position. (2) |
CENTER | Represents the center position. (3) |
Interhaptics Constant INTERHAPTICS_GROUP_ID
The GroupID enum represents the group IDs for different body parts. Each group has a unique ID assigned to it for grouping purposes. The following are some of the groups and their corresponding IDs:
| Member | Description |
|---|---|
UNKNOWN | Represents an unknown group. ID -1 |
ALL | Represents all body parts. ID 0 |
TOP | Represents the top portion of the body. ID 100 |
DOWN | Represents the lower portion of the body. ID 101 |
ARM | Represents the arm group. ID 200 |
HEAD | Represents the head group. ID 201 |
CHEST | Represents the chest group. ID 202 |
WAIST | Represents the waist group. ID 203 |
LEG | Represents the leg group. ID 204 |
UPPER_ARM | Represents the upper arm group. ID 300 |
LOWER_ARM | Represents the lower arm group. ID 301 |
HAND | Represents the hand group. ID 302 |
SKULL | Represents the skull group. ID 303 |
NECK | Represents the neck group. ID 304 |
UPPER_LEG | Represents the upper leg group. ID 305 |
LOWER_LEG | Represents the lower leg group. ID 306 |
FOOT | Represents the foot group. ID 307 |
PALM | Represents the palm group. ID 400 |
FINGER | Represents the finger group. ID 401 |
SOLE | Represents the sole group. ID 402 |
TOE | Represents the toe group. ID 403 |
THUMB | Represents the thumb group. ID 500 |
INDEX | Represents the index finger group. ID 501 |
MIDDLE | Represents the middle finger group. ID 502 |
RING | Represents the ring finger group. ID 503 |
PINKY | Represents the pinky finger group. ID 504 |
HALLUX | Represents the hallux group. ID 505 |
INDEX_TOE | Represents the index toe group. ID 506 |
MIDDLE_TOE | Represents the middle toe group. ID 507 |
RING_TOE | Represents the ring toe group. ID 508 |
PINKY_TOE | Represents the pinky toe group. ID 509 |
FIRST | Represents the first segment group. ID 600 |
SECOND | Represents the second segment group. ID 601 |
THIRD | Represents the third segment group. ID 602 |
Interhaptics Constant Interhaptics_CommandData
This structure represents an instruction that is useful for finding the body part to render. It contains the following members:
This struct is referenced by the following functions:
| Member | Type | Description |
|---|---|---|
| Sign | Any | {constant.INTERHAPTICS_OPERATOR} Represents the sign of the operation (+/-) of type Operator. |
| Group | Any | {constant.INTERHAPTICS_GROUP_ID} Represents the group targeted of type INTERHAPTICS_GROUP_ID. |
| Side | Any | {constant.INTERHAPTICS_LATERAL_FLAG} Represents the side targeted of type INTERHAPTICS_LATERAL_FLAG. |