Merge branch 'master' into Mario/stats_eloranking
[xonotic/xonotic-data.pk3dir.git] / qcsrc / server / items.qh
1 #pragma once
2
3 /// \file
4 /// \brief Header file that describes the functions related to game items.
5 /// \copyright GNU GPLv2 or any later version.
6
7 bool startitem_failed;
8
9 /// \brief Returns the item definition corresponding to the given class name.
10 /// \param[in] class_name Class name to search for.
11 /// \return Item definition corresponding to the given class name or NULL is not
12 /// found.
13 entity Item_FindDefinition(string class_name);
14
15 /// \brief Checks whether the items with the specified class name are allowed to
16 /// spawn.
17 /// \param[in] class_name Item class name to check.
18 /// \return True items with the specified class name are allowed to spawn, false
19 /// otherwise.
20 bool Item_IsAllowed(string class_name);
21
22 /// \brief Checks whether the items with the specified definition are allowed to
23 /// spawn.
24 /// \param[in] definition Item definition to check.
25 /// \return True items with the specified definition are allowed to spawn, false
26 /// otherwise.
27 bool Item_IsDefinitionAllowed(entity definition);
28
29 /// \brief Creates a new item.
30 /// \param[in] class_name Class name of the item.
31 /// \param[in] position Position of the item.
32 /// \param[in] no_align True if item should be placed directly at specified
33 /// position, false to let it drop to the ground.
34 /// \return Item on success, NULL otherwise.
35 entity Item_Create(string class_name, vector position, bool no_align);
36
37 /// \brief Initializes the item according to class name.
38 /// \param[in,out] item Item to initialize.
39 /// \param[in] class_name Class name to use.
40 /// \return No return.
41 /// \nore This function is useful if you want to set some item properties before
42 /// initialization.
43 void Item_Initialize(entity item, string class_name);
44
45 /// \brief Creates a loot item.
46 /// \param[in] class_name Class name of the item.
47 /// \param[in] position Position of the item.
48 /// \param[in] velocity of the item.
49 /// \param[in] time_to_live Amount of time after which the item will disappear.
50 /// \return Item on success, NULL otherwise.
51 entity Item_CreateLoot(string class_name, vector position, vector vel,
52         float time_to_live);
53
54 /// \brief Initializes the loot item.
55 /// \param[in] class_name Class name of the item.
56 /// \param[in] position Position of the item.
57 /// \param[in] velocity of the item.
58 /// \param[in] time_to_live Amount of time after which the item will disappear.
59 /// \return True on success, false otherwise.
60 /// \nore This function is useful if you want to set some item properties before
61 /// initialization.
62 bool Item_InitializeLoot(entity item, string class_name, vector position,
63         vector vel, float time_to_live);
64
65 /// \brief Returns whether the item is loot.
66 /// \param[in] item Item to check.
67 /// \return True if the item is loot, false otherwise.
68 bool Item_IsLoot(entity item);
69
70 /// \brief Sets the item loot status.
71 /// \param[in,out] item Item to adjust.
72 /// \param[in] loot Whether item is loot.
73 /// \return No return.
74 void Item_SetLoot(entity item, bool loot);
75
76 /// \brief Returns whether item should keep its position or be dropped to the
77 /// ground.
78 /// \param[in] item Item to check.
79 /// \return True if item should keep its position or false if it should be
80 /// dropped to the ground.
81 bool Item_ShouldKeepPosition(entity item);
82
83 /// \brief Returns whether the item is expiring (i.e. its strength, shield and
84 /// superweapon timers expire while it is on the ground).
85 /// \param[in] item Item to check.
86 /// \return True if the item is expiring, false otherwise.
87 bool Item_IsExpiring(entity item);
88
89 /// \brief Sets the item expiring status (i.e. whether its strength, shield
90 /// and superweapon timers expire while it is on the ground).
91 /// \param[in,out] item Item to adjust.
92 /// \param[in] expiring Whether item is expiring.
93 /// \return No return.
94 void Item_SetExpiring(entity item, bool expiring);