Inventory API 1.1.0

This resource provides an inventory API to server developers.

This resource will not save anything on its own, it just provides you the functions to make your own inventory system using CEF/NativeUI/commands.

 

Installing

• Put the files you downloaded in their respective places
• Read the documentation and examples to set up some items etc.
• All done

 

Features

• Easy to use (hopefully!)
• Events
• Custom attributes for items (see examples)

 

Inventory API

const invAPI = require("../inventory-api");

/**
 * Adds an item to the inventory system.
 * @param {string} key         Item identifier, such as "item_medkit".
 * @param {string} name        Item name, such as "Medkit".
 * @param {string} description Item description, such as "Gives you 10 health".
 * @param {function} [onUse]       Optional - Function that gets called when the item is used.
 * @param {function} [nameFunc]    Optional - Function that gets called when getItemName() is used.
 * @param {function} [descFunc]    Optional - Function that gets called when getItemDescription() is used.
 * @return {object} The added item, will be null if there are any mistakes.
 * @fires itemDefined
 */
invAPI.addItem(key, name, description, onUse, nameFunc, descFunc);

/**
 * Returns whether the specified key is a registered or not.
 * @param  {string}  key Item identifier, such as "item_medkit".
 * @return {Boolean}     True if registered, false otherwise.
 */
invAPI.hasItem(key);

/**
 * Returns the specified item.
 * @param  {string} key Item identifier, such as "item_medkit".
 * @return {object}     The item at the specified key, will be undefined if the key isn't registered.
 */
invAPI.getItem(key);

/**
 * Returns all registered item identifiers.
 * @return {string[]} An array of registered item identifiers.
 */
invAPI.getAllItems();

/**
 * Returns the human readable name of the specified item.
 * @param  {string} key Item identifier, such as "item_medkit".
 * @param  {string} [data] Optional - An object that has item attributes.
 * @return {string}     Human readable item name.
 */
invAPI.getItemName(key, data);

/**
 * Returns the description of the specified item.
 * @param  {string} key Item identifier, such as "item_medkit".
 * @param  {string} [data] Optional - An object that has item attributes.
 * @return {string}     Item's description.
 */
invAPI.getItemDescription(key, data);

 

Inventory API Events

/**
 * itemDefined
 * This event is called when an item is added to the system with invAPI.addItem()
 * @param {string} key Item identifier.
 * @param {string} name Human readable name of the item.
 * @param {string} description Description of the item.
 */
invAPI.on("itemDefined", (key, name, description) => {
    // Example: console.log(`Item defined, key: ${key} | name: ${name} | description: ${description}`);
});

/**
 * itemAdded
 * This event is called when a player receives an item.
 * @param {player} player The player who received the item.
 * @param {string} key Item identifier.
 * @param {number} amount Amount the player received.
 * @param {object} data Item attributes.
 */
invAPI.on("itemAdded", (player, key, amount, data) => {
    // Example: console.log(`${player.name} received ${amount}x ${key}.`);
});

/**
 * itemUsed
 * This event is called when a player uses an item.
 * @param {player} player The player who used the item.
 * @param {number} invIdx Index of the item in player's inventory.
 * @param {string} key Item identifier.
 * @param {object} data Item attributes.
 */
invAPI.on("itemUsed", (player, invIdx, key, data) => {
    // Example: console.log(`${player.name} used ${key}.`);
});

/**
 * itemRemoved
 * This event is called when an item is removed from a player's inventory.
 * @param {player} player The player who lost an item.
 * @param {number} invIdx Index of the item that got removed in player's inventory.
 * @param {string} key Item identifier.
 * @param {number} amount Removed item amount.
 * @param {object} data Item attributes.
 */
invAPI.on("itemRemoved", (player, invIdx, key, amount, data) => {
    // Example: console.log(`${player.name} lost ${amount}x ${key}.`);
});

/**
 * itemRemovedCompletely
 * This event is called when an item is no longer in a player's inventory.
 * @param {player} player The player who lost an item.
 * @param {string} key Item identifier.
 * @param {object} data Item attributes.
 */
invAPI.on("itemRemovedCompletely", (player, key, data) => {
    // Example: console.log(`${player.name} no longer has ${key} (${data ? "with data" : "without data"}) in their inventory.`);
});

/**
 * inventoryReplaced
 * This event is called when a player's inventory array gets changed by player.setInventory()
 * @param {player} player The player who had an inventory change.
 * @param {object[]} oldInventory The player's old inventory array.
 * @param {object[]} newInventory The player's new inventory array.
 */
invAPI.on("inventoryReplaced", (player, oldInventory, newInventory) => {
    // Example: console.log(`${player.name} had their inventory replaced. (Old item count: ${oldInventory.length}, new: ${newInventory.length})`);
});

 

Player API

/**
 * Returns the inventory array of the player.
 * @return {object[]} An array that holds all items of the player.
 */
player.getInventory();

/**
 * Replaces the inventory array of the player with the specified one.
 * @param {Array} newInventory An array that's going to be the new inventory of the player.
 * @return {Boolean} True if successful, false otherwise.
 * @fires inventoryReplaced
 */
player.setInventory(newInventory);

/**
 * Returns whether the player has the specified item or not.
 * @param  {string}  itemKey Item identifier.
 * @return {Boolean}         True if player has the item, false otherwise.
 */
player.hasItem(itemKey);

/**
 * Same as hasItem but for items with custom attributes.
 * @param  {string}  itemKey Item identifier.
 * @param  {object}  data    An object that has item attributes.
 * @return {Boolean}         True if player has the item, false otherwise.
 */
player.hasItemWithData(itemKey, data);

/**
 * Gets the item's index in the player's inventory.
 * @param  {string} itemKey Item identifier.
 * @return {number}         Index of the item, -1 if not found.
 */
player.getItemIndex(itemKey);

/**
 * Same as getItemIndex but for items with custom attributes.
 * @param  {string} itemKey Item identifier.
 * @param  {object} data    An object that has item attributes.
 * @return {number}         Index of the item, -1 if not found.
 */
player.getItemIndexWithData(itemKey, data);

/**
 * Gets how many of the specified item exists in the player's inventory.
 * @param  {string} itemKey Item identifier.
 * @return {number}         Item amount.
 */
player.getItemAmount(itemKey);

/**
 * Same as getItemAmount but for items with custom attributes.
 * @param  {string} itemKey Item identifier.
 * @param  {object} data    An object that has item attributes.
 * @return {number}         Item amount.
 */
player.getItemAmountWithData(itemKey, data);

/**
 * Gets total amount of items the player has in their inventory.
 * @return {number} Amount of all items.
 */
player.getTotalItemAmount();

/**
 * Gives the specified item to the player.
 * @param  {string} itemKey Item identifier.
 * @param  {number} amount  Amount to give.
 * @param  {object} [data]    Optional - An object that has item attributes.
 * @return {Boolean}         True if successful, false otherwise.
 * @fires itemAdded
 */
player.giveItem(itemKey, amount, data);

/**
 * Uses the item at the specified index of the player's inventory array.
 * @param  {number} itemIdx Index of the item in player's inventory array.
 * @return {Boolean}         True if successful, false otherwise.
 * @fires itemUsed
 */
player.useItem(itemIdx);

/**
 * Removes the item at the specified index of the player's inventory array.
 * @param  {number} itemIdx Index of the item in player's inventory array.
 * @param  {number} [amount]  Optional - Amount to remove.
 * @return {Boolean}         True if successful, false otherwise.
 * @fires itemRemoved
 * @fires itemRemovedCompletely
 */
player.removeItem(itemIdx, amount);

 

Examples

Full Test Script (used during development): https://gist.github.com/root-cause/6f15f0ee2276872c2d15a5333fed6a10

Name/Description Function Test Script: https://gist.github.com/root-cause/500b6e197348e941aeebfa8f883486bb

Source code is available on GitHub in case you don't want to download: https://github.com/root-cause/ragemp-inventory-api

const drinkItem = invAPI.addItem("item_drink", "Drink", "Generic drink.");

drinkItem.nameFunc = function(data) {
    if (data && data.hasOwnProperty("drinkType")) {
        return `Drink (${data.drinkType})`;
    } else {
        return "Drink";
    }
};

drinkItem.descFunc = function(data) {
    if (data && data.hasOwnProperty("drinkType")) {
        switch (data.drinkType) {
            case "wine":
                return "Wine description.";

            case "water":
                return "Water description.";
        }
    } else {
        return "Generic drink.";
    }
};

// Outputs
console.log(invAPI.getItemName("item_drink")); // Drink
console.log(invAPI.getItemName("item_drink", { drinkType: "wine" })); // Drink (wine)
console.log(invAPI.getItemName("item_drink", { drinkType: "water" })); // Drink (water)

console.log(invAPI.getItemDescription("item_drink")); // Generic drink.
console.log(invAPI.getItemDescription("item_drink", { drinkType: "wine" })); // Wine description.
console.log(invAPI.getItemDescription("item_drink", { drinkType: "water" })); // Water description.