From 29c6971e6a6141cf481bb7a67ad31d633fb20e1f Mon Sep 17 00:00:00 2001 From: Nord1cWarr1or <47604048+Nord1cWarr1or@users.noreply.github.com> Date: Fri, 2 Jun 2023 02:42:43 +0000 Subject: [PATCH 1/4] Update box_with_boxes.inc Added description --- .../scripting/include/box_with_boxes.inc | 98 +++++++++++++------ 1 file changed, 68 insertions(+), 30 deletions(-) diff --git a/addons/amxmodx/scripting/include/box_with_boxes.inc b/addons/amxmodx/scripting/include/box_with_boxes.inc index cb425ca..cd25b78 100644 --- a/addons/amxmodx/scripting/include/box_with_boxes.inc +++ b/addons/amxmodx/scripting/include/box_with_boxes.inc @@ -12,52 +12,90 @@ #pragma library box_with_boxes #endif -/* -* TODO -*/ +/** + * Creates a box of the specified type with the specified origin, minimums, and maximums. + * + * @param type The type of the box. + * @param origin The origin of the box. + * @param mins The minimums of the box. + * @param maxs The maximums of the box. + */ native bwb_create_box(const type[], Float:origin[3], Float:mins[3], Float:maxs[3]); -/* -* TODO -*/ +/** + * Registers a box type with the specified type and color. + * + * @param type The type of the box. + * @param color The color of the box. + */ native bwb_register_box_type(const type[], color[3] = {255, 255, 255}); -/* -* TODO -*/ +/** + * Gets the index of the specified box type. + * + * @param type The type of the box. + * + * @return The index of the box type. + */ native bwb_get_type_index(const type[]); -/* -* TODO -*/ +/** + * Gets the type of the specified box. + * + * @param box The index of the box. + * @param type The type of the box. + * @param len The length of the type of the box. + */ native bwb_get_box_type(box, type[], len); -/* -* TODO -*/ +/** + * Called when an entity starts touching a box. + * + * @param box The index of the box. + * @param ent The entity that is touching the box. + * @param type_index The index of the box type. + */ forward bwb_box_start_touch(box, ent, type_index); -/* -* TODO -*/ +/** + * Called when an entity stops touching a box. + * + * @param box The index of the box. + * @param ent The entity that stopped touching the box. + * @param type_index The index of the box type. + */ forward bwb_box_stop_touch(box, ent, type_index); -/* -* TODO -*/ +/** + * Called when an entity touches a box. + * + * @param box The index of the box. + * @param ent The entity that is touching the box. + * @param type_index The index of the box type. + */ forward bwb_box_touch(box, ent, type_index); -/* -* TODO -*/ +/** + * Called when an entity invalidly touches a box. + * + * @param box The index of the box. + * @param ent The entity that invalidly touched the box. + * @param type_index The index of the box type. + */ forward bwb_box_invalid_touch(box, ent, type_index); -/* -* TODO -*/ +/** + * Called when a box is created. + * + * @param box The index of the box. + * @param type The type of the box. + */ forward bwb_box_created(box, const type[]); -/* -* TODO -*/ +/** + * Called when a box is deleted. + * + * @param box The index of the box. + * @param type The type of the box. + */ forward bwb_box_deleted(box, const type[]); From 6b894d74982628717de9284be7c26f5a3cad72cf Mon Sep 17 00:00:00 2001 From: Nord1cWarr1or <47604048+Nord1cWarr1or@users.noreply.github.com> Date: Fri, 2 Jun 2023 02:43:30 +0000 Subject: [PATCH 2/4] Update box_with_boxes_stocks.inc added description --- .../include/box_with_boxes_stocks.inc | 26 +++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/addons/amxmodx/scripting/include/box_with_boxes_stocks.inc b/addons/amxmodx/scripting/include/box_with_boxes_stocks.inc index cf998dd..f62ff89 100644 --- a/addons/amxmodx/scripting/include/box_with_boxes_stocks.inc +++ b/addons/amxmodx/scripting/include/box_with_boxes_stocks.inc @@ -3,6 +3,14 @@ #endif #define _box_with_boxes_stocks_included +/** + * Determines if two entities intersect. + * + * @param a The first entity. + * @param b The second entity. + * + * @return True if the entities intersect, false otherwise. + */ stock intersect(a, b) { new Float:amins[3], Float:amaxs[3]; pev(a, pev_absmin, amins); @@ -16,6 +24,16 @@ stock intersect(a, b) { (amins[2] <= bmaxs[2] && amaxs[2] >= bmins[2]); } +/** + * Calculates the distance between two boxes. + * + * @param mins1 The minimums of the first box. + * @param maxs1 The maximums of the first box. + * @param mins2 The minimums of the second box. + * @param maxs2 The maximums of the second box. + * + * @return The distance between the two boxes. + */ stock Float:fm_boxes_distance(const Float:mins1[3], const Float:maxs1[3], const Float:mins2[3], const Float:maxs2[3]) { new Float:dist[3]; for (new i = 0; i < 3; ++i) { @@ -28,6 +46,14 @@ stock Float:fm_boxes_distance(const Float:mins1[3], const Float:maxs1[3], const return vector_length(dist); } +/** + * Calculates the distance between two box entities. + * + * @param boxent1 The first box entity. + * @param boxent2 The second box entity. + * + * @return The distance between the two box entities. + */ stock Float:fm_boxents_distance(boxent1, boxent2) { new Float:mins1[3], Float:maxs1[3]; pev(boxent1, pev_absmin, mins1); From f9d5965d66bf1fb4e8be2d3cc104bd65366c44ea Mon Sep 17 00:00:00 2001 From: Nord1cWarr1or Date: Thu, 28 Aug 2025 23:41:43 +0300 Subject: [PATCH 3/4] includes: rewrite API description --- .../scripting/include/box_with_boxes.inc | 101 +++++++++++------- .../include/box_with_boxes_stocks.inc | 27 +---- 2 files changed, 68 insertions(+), 60 deletions(-) diff --git a/addons/amxmodx/scripting/include/box_with_boxes.inc b/addons/amxmodx/scripting/include/box_with_boxes.inc index cd25b78..bb54a04 100644 --- a/addons/amxmodx/scripting/include/box_with_boxes.inc +++ b/addons/amxmodx/scripting/include/box_with_boxes.inc @@ -13,89 +13,114 @@ #endif /** - * Creates a box of the specified type with the specified origin, minimums, and maximums. + * Creates a new box entity. * - * @param type The type of the box. - * @param origin The origin of the box. - * @param mins The minimums of the box. - * @param maxs The maximums of the box. + * @param type Type name of the box to create. This type should be registered. + * @param origin A vector representing the world coordinates for the box's center. + * @param mins A vector for the minimum bounding box coordinates, relative to the origin. + * @param maxs A vector for the maximum bounding box coordinates, relative to the origin. + * + * @return Entity index of the newly created box, or 0 on failure. */ native bwb_create_box(const type[], Float:origin[3], Float:mins[3], Float:maxs[3]); /** - * Registers a box type with the specified type and color. + * Registers a new box type or retrieves index of an existing one. + * This allows for custom categorization and visualization of boxes. + * + * @param type Name of the type to register (e.g., "teleport", "damage_zone"). + * @param color Optional RGB color array for visualizing the box in edit mode. * - * @param type The type of the box. - * @param color The color of the box. + * @return Unique index for Registered type. */ native bwb_register_box_type(const type[], color[3] = {255, 255, 255}); /** - * Gets the index of the specified box type. + * Retrieves index of a registered box type. * - * @param type The type of the box. + * @param type Name of the type to look up. * - * @return The index of the box type. + * @return Index of the type if found, -1 otherwise. */ native bwb_get_type_index(const type[]); /** - * Gets the type of the specified box. + * Gets the type name of a given box entity. + * + * @param box Entity index of the box. + * @param type Output buffer to store the type name. + * @param len Maximum length of the output buffer. * - * @param box The index of the box. - * @param type The type of the box. - * @param len The length of the type of the box. + * @noreturn */ native bwb_get_box_type(box, type[], len); /** - * Called when an entity starts touching a box. + * Called when an entity starts touching a box (i.e., on the first frame of collision). * - * @param box The index of the box. - * @param ent The entity that is touching the box. - * @param type_index The index of the box type. + * @param box Entity index of the box being touched. + * @param ent Entity index that is touching the box. + * @param type_index Registered index of the box's type. + * + * @noreturn */ forward bwb_box_start_touch(box, ent, type_index); /** - * Called when an entity stops touching a box. + * Called when an entity stops touching a box (i.e., on the first frame it is no longer colliding). + * + * @param box Entity index of the box. + * @param ent Entity index that was touching the box. + * @param type_index Registered index of the box's type. * - * @param box The index of the box. - * @param ent The entity that stopped touching the box. - * @param type_index The index of the box type. + * @noreturn */ forward bwb_box_stop_touch(box, ent, type_index); /** - * Called when an entity touches a box. + * Called every frame an entity is touching/colliding with a box. + * This is called continuously between bwb_box_start_touch and bwb_box_stop_touch. * - * @param box The index of the box. - * @param ent The entity that is touching the box. - * @param type_index The index of the box type. + * @param box Entity index of the box being touched. + * @param ent Entity index that is touching the box. + * @param type_index Registered index of the box's type. + * + * @noreturn */ forward bwb_box_touch(box, ent, type_index); /** - * Called when an entity invalidly touches a box. + * Called when an entity that was touching a box becomes invalid. + * This typically happens if a player disconnects or an entity is removed + * while inside a box volume. + * + * @note The 'ent' parameter is an invalid entity index. Do not use it + * with any engine functions that expect a valid entity. + * + * @param box Entity index of the box. + * @param ent Entity index (now invalid) that was touching the box. + * @param type_index Registered index of the box's type. * - * @param box The index of the box. - * @param ent The entity that invalidly touched the box. - * @param type_index The index of the box type. + * @noreturn */ forward bwb_box_invalid_touch(box, ent, type_index); /** - * Called when a box is created. + * Called after a new box has been created. * - * @param box The index of the box. - * @param type The type of the box. + * @param box Entity index of the newly created box. + * @param type Type name of the created box. + * + * @noreturn */ forward bwb_box_created(box, const type[]); /** - * Called when a box is deleted. + * Called just before a box is deleted. + * + * @param box Entity index of the box being deleted. + * @param type Type name of the box being deleted. * - * @param box The index of the box. - * @param type The type of the box. + * @noreturn */ -forward bwb_box_deleted(box, const type[]); +forward bwb_box_deleted(box, const type[]); \ No newline at end of file diff --git a/addons/amxmodx/scripting/include/box_with_boxes_stocks.inc b/addons/amxmodx/scripting/include/box_with_boxes_stocks.inc index f62ff89..5e94653 100644 --- a/addons/amxmodx/scripting/include/box_with_boxes_stocks.inc +++ b/addons/amxmodx/scripting/include/box_with_boxes_stocks.inc @@ -4,12 +4,13 @@ #define _box_with_boxes_stocks_included /** - * Determines if two entities intersect. + * Checks if the bounding boxes of two entities intersect. * - * @param a The first entity. - * @param b The second entity. + * @note This function is commonly used to determine if a player is inside a box volume. * - * @return True if the entities intersect, false otherwise. + * @param a Entity index of the first object. + * @param b Entity index of the second object. + * @return Returns true if the entities' bounding boxes are intersecting, false otherwise. */ stock intersect(a, b) { new Float:amins[3], Float:amaxs[3]; @@ -24,16 +25,6 @@ stock intersect(a, b) { (amins[2] <= bmaxs[2] && amaxs[2] >= bmins[2]); } -/** - * Calculates the distance between two boxes. - * - * @param mins1 The minimums of the first box. - * @param maxs1 The maximums of the first box. - * @param mins2 The minimums of the second box. - * @param maxs2 The maximums of the second box. - * - * @return The distance between the two boxes. - */ stock Float:fm_boxes_distance(const Float:mins1[3], const Float:maxs1[3], const Float:mins2[3], const Float:maxs2[3]) { new Float:dist[3]; for (new i = 0; i < 3; ++i) { @@ -46,14 +37,6 @@ stock Float:fm_boxes_distance(const Float:mins1[3], const Float:maxs1[3], const return vector_length(dist); } -/** - * Calculates the distance between two box entities. - * - * @param boxent1 The first box entity. - * @param boxent2 The second box entity. - * - * @return The distance between the two box entities. - */ stock Float:fm_boxents_distance(boxent1, boxent2) { new Float:mins1[3], Float:maxs1[3]; pev(boxent1, pev_absmin, mins1); From f701157e7f327d3334855afed10051280aec68b0 Mon Sep 17 00:00:00 2001 From: Nord1cWarr1or Date: Sat, 6 Sep 2025 18:36:00 +0300 Subject: [PATCH 4/4] includes: delete stock description --- .../amxmodx/scripting/include/box_with_boxes_stocks.inc | 9 --------- 1 file changed, 9 deletions(-) diff --git a/addons/amxmodx/scripting/include/box_with_boxes_stocks.inc b/addons/amxmodx/scripting/include/box_with_boxes_stocks.inc index 5e94653..cf998dd 100644 --- a/addons/amxmodx/scripting/include/box_with_boxes_stocks.inc +++ b/addons/amxmodx/scripting/include/box_with_boxes_stocks.inc @@ -3,15 +3,6 @@ #endif #define _box_with_boxes_stocks_included -/** - * Checks if the bounding boxes of two entities intersect. - * - * @note This function is commonly used to determine if a player is inside a box volume. - * - * @param a Entity index of the first object. - * @param b Entity index of the second object. - * @return Returns true if the entities' bounding boxes are intersecting, false otherwise. - */ stock intersect(a, b) { new Float:amins[3], Float:amaxs[3]; pev(a, pev_absmin, amins);