alt:V Athena Docs
Search…
Configuration
Glossary
Basic Scripting
Adding Items
Learn how to add items to your game mode.
Adding Items
Video Guide
Keywords and Inventory Syntax
The inventory is setup in a way to have multiple pages. Which means it is an array of array(s). Which is a bit of a weird concept if you're only used to a single array of items.
What this means is that each array inside of the inventory has the items in it.
So accessing individual items for a player is something like...
1
player.data.inventory[0][0]
Copied!
This will get the first
tab or page of the player's inventory and the first item in the tab or page.Here's what they may look like from a visual perspective.
1
[
2
[
3
{
4
name: 'Burger',
5
description: 'A delicious burger...',
6
quantity: 1,
7
slot: 0
8
}
9
],
10
[],
11
[],
12
[],
13
[],
14
[],
15
[
16
{
17
name: 'Taco',
18
description: 'A classic Mexican street taco.',
19
quantity: 0,
20
slot: 5
21
}
22
]
23
]
Copied!
Difference Between Slot and Index
Slot is where the item is placed when the item is displayed to the user.
Index is where the item is placed inside of the array.
If a function returns an index for an inventory item then it means you can get the item like...
1
player.data.inventory[someTabNumber][index]
Copied!
If the function returns a slot for an inventory item. Then it means you need to get it like this...
1
const item = player.data.inventory[someTabNumber].find(x => x.slot === someSlotNumber);
Copied!
Using Inventory Functions
The inventory does not always save after each update. If you use any inventory functions you should be throwing a save.
1
playerFuncs.save.field(player, 'inventory', player.data.inventory);
Copied!
Deep Cloning Objects
Because these objects can be rather complicated there is a simple function that does a deep clone of an object and ensuring that you're not modifying the original data. You should always deep clone an object before adding it to a player inventory to prevent data from referencing other inventories and such.
1
const item = deepCloneObject(originalItem) as Item;
2
// Then add the item somewhere...
Copied!
Add / Create Items
Items come in a variety of flavors but their general creation follows a specific template.
1
const refItem: Item = {
2
name: `Micro SMG`,
3
uuid: `some_hash_thing`,
4
description: `Debug: Should be able to go to toolbar. Cannot go to equipment. Is a weapon.`,
5
icon: 'gun',
6
slot: 4,
7
quantity: 1,
8
behavior: ITEM_TYPE.CAN_DROP | ITEM_TYPE.CAN_TRADE | ITEM_TYPE.IS_TOOLBAR | ITEM_TYPE.IS_WEAPON,
9
data: {
10
hash: 0x13532244 // Used as the weapon hash for giving the player a weapon
11
}
12
};
Copied!
Now when you create templates for items and want to use a reference item like the one above. You must perform a deep copy of that item reference.
1
const newItem: Item = deepCloneObject<Item>(refItem);
Copied!
After making the deepl clone of your object you can modify it.
1
newItem.name = `Super Cool Item`;
2
newItem.icon = 'crate';
Copied!
Giving Players Items
More often than not the one location you will be putting new items in the player's inventory. Athena comes with a handful of utility functions to help you add and remove items from a player's inventory.
Here's the basic gist of it.
1
const slotInfo = playerFuncs.inventory.getFreeInventorySlot(player);
2
playerFuncs.inventory.inventoryAdd(player, newItem, slotInfo.slot, slotInfo.tab);
3
​
4
// Don't forget to save the inventory after adding it.
5
playerFuncs.save.field(player, 'inventory', player.data.inventory);
Copied!
Removing Players Items
If you need to remove a player's item you can run the following functions to check if it is removed.
1
const slotInfo: { slot: number; tab: number } | null = playerFuncs.inventory.isInInventory({ name: 'Micro SMG' });
2
if (!slotInfo) {
3
playerFuncs.emit.message(player, `Item was not found!`);
4
return;
5
}
6
​
7
const item: Item = playerFuncs.inventory.getInventoryItem(player, slotInfo.slot, slotInfo.tab);
8
if (!item) {
9
playerFuncs.emit.message(player, `Item was not found!`);
10
return;
11
}
12
​
13
const didRemoveItem: boolean = playerFuncs.inventory.inventoryRemove(player, slotInfo.slot, slotInfo.tab);
14
if (!didRemoveItem) {
15
playerFuncs.emit.message(player, `Did not find item to remove!`);
16
return;
17
}
18
​
19
alt.log(`The item was removed!`);
Copied!
Working with Player Inventories
Depending on what you want to do with the player inventory there are a ton of ways to work with it. However, more often than not the most common use case for working with an inventory is finding an item and removing it. Which is what we'll be covering here.
1
import * as alt from 'alt-server';
2
import { playerFuncs } from '../../server/extensions/Player';
3
​
4
function findPlayerBurgerItem(player: alt.Player) {
5
const someItemInfo = playerFuncs.inventory.isInInventory(player, { name: 'Burger' });
6
if (!someItemInfo) {
7
// Item does not exist.
8
return;
9
}
10
​
11
const item = player.data.inventory[someItemInfo.tab][someItemInfo.index];
12
console.log(item);
13
}
14
​
15
// Removes an item based on the `slot` of the item.
16
function removePlayerBurgerItem(player: alt.Player, tab: number, slot: number) {
17
playerFuncs.inventory.inventoryRemove(player, slot, tab);
18
}
Copied!
Item Effects
If you wish to use item effects when you consume an item it's quite simple.
You will need to add a
event to the data section of your item.When the item is consumed it will reduce the quantity by
1 and then call that event over alt.emit.It can then be recieved with
alt.on.Item Example
1
const teleporterItem: Item = {
2
name: `Teleporter`,
3
uuid: `teleporter`,
4
description: `Debug: Should be able to call an event with this`,
5
icon: 'teleporter',
6
slot: 5,
7
quantity: 1,
8
behavior: ITEM_TYPE.CAN_DROP | ITEM_TYPE.CAN_TRADE | ITEM_TYPE.CONSUMABLE,
9
data: {
10
event: 'effect:Teleport'
11
}
12
};
Copied!
Item Effect Receive
1
import * as alt from 'alt-server';
2
import { playerFuncs } from '../../server/extensions/Player';
3
import { Item } from '../../shared/interfaces/Item';
4
​
5
alt.on('effect:Teleport', (player: alt.Player, item: Item) => {
6
playerFuncs.emit.message(player, `You consumed ${item.name}`);
7
});
Copied!
Last modified 3mo ago