Iris: An Interaction Library 1.0.0

Iris is a raycast based interaction system with two components: the core library and a basic interaction UI which can be reimplemented by server developers to fit their needs, making it highly customizable.

Installing

• Put the files you downloaded in their respective places
• Add require("iris") to client_packages/index.js
• (Optional) Add require("iris-ui") to client_packages/index.js or build your own UI to handle interactions with

Clientside API

The library defines a global object named Iris that can be used to interact with the library. Here are its members:

Constants

The Iris global object has a property called SearchType which acts as an enum to avoid magic values in code:

Iris.SearchType.Invalid // 0
Iris.SearchType.EntityType // 1
Iris.SearchType.EntityModel // 2
Iris.SearchType.EntityHandle // 3
Iris.SearchType.NumSearchTypes // 4

Functions

/**
 * Creates an interaction.
 * @param {number} searchType
 * @param {number} target
 * @param {object} interaction Must have a `name` property. `order` (number) is also an optional property to display the interaction above/below other interactions.
 * @returns {number} The interaction ID which can be used with `getInteraction` and `removeInteraction` functions.
 */
Iris.createInteraction(searchType, target, interaction);

/**
 * Returns the interaction with the specified ID.
 * @param {number} interactionId
 * @returns {object|undefined} The interaction object if found, `undefined` otherwise.
 */
Iris.getInteraction(interactionId);

/**
 * Removes the interaction with the specified ID.
 * @param {number} interactionId
 * @returns {boolean} `true` if the removal is successful, `false` otherwise.
 */
Iris.removeInteraction(interactionId);

/**
 * Returns whether the library is scanning for interactions or not.
 * @returns {boolean}
 */
Iris.isActive();

/**
 * Sets the interaction scanning status of the library.
 * @fires `iris::stateChange` clientside event with the first argument being the new scanning status.
 * @param {boolean} value
 */
Iris.setActive(value);

/**
 * Returns the distance used for the interaction scanning raycast.
 * @returns {number}
 */
Iris.getRaycastDistance();

/**
 * Sets the distance used for the interaction scanning raycast.
 * @param {number} newDistance
 */
Iris.setRaycastDistance(newDistance);

/**
 * Returns the flags used for the interaction scanning raycast. Refer to: https://wiki.rage.mp/index.php?title=Raycasting::testPointToPoint
 * @returns {number}
 */
Iris.getRaycastFlags();

/**
 * Sets the flags used for the interaction scanning raycast. Refer to: https://wiki.rage.mp/index.php?title=Raycasting::testPointToPoint
 * @param {number} newFlags
 */
Iris.setRaycastFlags(newFlags);

/**
 * Returns the handle of the last entity that was hit by the interaction scanning raycast.
 * @returns {number}
 */
Iris.getLastEntityHandle();

Events

The library uses RAGEMP's clientside events.

/**
 * iris::stateChange is called when scanning for interactions is enabled/disabled.
 * @param {boolean} newState `true` if scanning, `false` otherwise.
 */
mp.events.add("iris::stateChange", function(newState) {
    // your code here
});

/**
 * iris::focusChange is called when the entity detected by the interaction scanner changes.
 * @param {object} focusChangeContext
 * @param {number} focusChangeContext.newEntityHandle
 * @param {number} focusChangeContext.oldEntityHandle
 * @param {number|undefined} focusChangeContext.newEntityType
 * @param {number|undefined} focusChangeContext.newEntityModel
 * @param {object[]|undefined} focusChangeContext.interactions The available interactions for the new entity.
 * @param {object|undefined} focusChangeContext.raycastResult The raycast result that was responsible for calling this event, set only if the `focusChangeContext.newEntityHandle` is valid. Refer to: https://wiki.rage.mp/index.php?title=Raycasting::testPointToPoint
 */
mp.events.add("iris::focusChange", function(focusChangeContext) {
    // your code here
});

Example Script

// https://wiki.rage.mp/index.php?title=Entity::getType
const ENTITY_TYPE_VEHICLE = 2;
const ENTITY_TYPE_OBJECT = 3;

// Create some interactions
// "eventName" and "selectedFn" properties only work with the default iris-ui script, they're intended to show two simple ways to handle interactions.
const myVehicleInteraction = Iris.createInteraction(Iris.SearchType.EntityType, ENTITY_TYPE_VEHICLE, {
    name: "Generic vehicle interaction (get remoteId)",
    eventName: "my_custom_event_name"
});

const myObjectInteraction = Iris.createInteraction(Iris.SearchType.EntityType, ENTITY_TYPE_OBJECT, {
    name: "Generic object interaction (get handle)",
    selectedFn: function(entityHandle) {
        mp.gui.chat.push(`This object's handle is: ${entityHandle}`);
    }
});

const adderOnlyInteraction = Iris.createInteraction(Iris.SearchType.EntityModel, mp.game.joaat("adder"), {
    name: "Adder only interaction",
    eventName: "adder_option_clicked",
    order: 99 // make it the top option
});

// Liquor store example (non-functional)
const mp_m_shopkeep_01 = mp.game.joaat("mp_m_shopkeep_01");
mp.peds.new(mp_m_shopkeep_01, new mp.Vector3(-2966.05, 391.43, 15.05), 90.0, 0);

// Options for the shopkeeper
Iris.createInteraction(Iris.SearchType.EntityModel, mp_m_shopkeep_01, { name: "Ask about his day"});
Iris.createInteraction(Iris.SearchType.EntityModel, mp_m_shopkeep_01, { name: "Pay for items" });
Iris.createInteraction(Iris.SearchType.EntityModel, mp_m_shopkeep_01, { name: "Threaten" });

// Options for various items inside the store
Iris.createInteraction(Iris.SearchType.EntityModel, mp.game.joaat("v_ret_ml_sweetego"), { name: "Add EgoChaser to cart ($5)" });
Iris.createInteraction(Iris.SearchType.EntityModel, mp.game.joaat("v_ret_ml_sweet4"), { name: "Add Sweet Nothings to cart ($2)" });
Iris.createInteraction(Iris.SearchType.EntityModel, mp.game.joaat("v_ret_ml_sweet3"), { name: "Add P's & Q's to cart ($1)" });
Iris.createInteraction(Iris.SearchType.EntityModel, mp.game.joaat("v_ret_ml_beeram"), { name: "Add A. M. Beer (6-pack) to cart ($12)" });
Iris.createInteraction(Iris.SearchType.EntityModel, mp.game.joaat("v_ret_ml_beerdus"), { name: "Add Dusche Gold (6-pack) to cart ($14)" })

// Event handlers
function handleGetVehicleRemoteId(entityHandle) {
    const vehicle = mp.vehicles.atHandle(entityHandle);
    if (vehicle) {
        mp.gui.chat.push(`This vehicle's remoteId is: ${vehicle.remoteId}`);
    }
}

function handleAdderClick() {
    mp.gui.chat.push("You found the adder exclusive interaction... aaand it's gone.");
    Iris.removeInteraction(adderOnlyInteraction);
    Iris.setActive(false);
}

// Register event handlers
mp.events.add({
    "my_custom_event_name": handleGetVehicleRemoteId,
    "adder_option_clicked": handleAdderClick
});

Source code is also available on GitHub: https://github.com/root-cause/ragemp-iris