[HamletEagle]

WeaponBoxApi
Release: 09.04.2015 | Last Update: 09.04.2015

Table of Contents

• Description
• Requirements
• Installation
• API
• Credits
• Changelog

Description top

This api give acces to WeaponBox functions from game, making weaponbox manipulation much more easier than ever before.
Usually you would need to redo this functions in pawn, this work si workill and in my opinion is for nothing. Now, you can use just 5 natives and to the job perfectly.

You may ask where you need this. Well, if you are not a coder or if you don't know what a weaponbox entity is your don't need that for sure.

Requirements top

You need the fallowing things to get this working:

• Orpheu module
• An updated server without dproto.
  Signatures may not work into outdated server.

Installation top

To install the plugin:

1. Download the resources from this post. You need to get the source and compile it locally.
2. Put WeaponBoxApi.amxx in addons/amxmodx/plugins
3. Open addons/amxmodx/configs/plugins.ini and add at the end of this file WeaponBoxApi.amxx
4. You can put WeaponBoxApi.sma file into addons/amxmodx/sources but this is not mandatory.
5. Open the archive provided and copy the content from Orpheu folder into addons/amxmodx/configs/Orpheu(you need to have orpheu installed)

To install orpheu:

1. Download orpheu files and extract the archive.
2. Copy the dll/so file depending on your operation system into addons/amxmodx/modules
3. The module will be auto-loaded, you don't need to add it into modules.ini

To compile locally:

• First way:
  1. Download AMX Mod X for windows/linux from main site
  2. Extract somewhere the arhive and remember the folder!
  3. Copy the content from include folder from orpheu arhive into addons/amxmodx/scripting/include( in the folder created in the step 2 ).
  4. Copy the content from include folder from WeaponBoxApi arhive into addons/amxmodx/scripting/include( in the folder created in the step 2 ).
  5. Download the source of the plugin( WeaponBoxApi.sma) from this post and drag it over the compile.exe(scripting folder from the arhive created at step 2)
  6. It will create a new folder called compiled. Open it and you will find your compiled plugin( WeaponBoxApi.amxx )
• Second way:
  1. Go to http://spider.limetech.org/
  2. Copy/paste the code from the .sma file into the website.
  3. Under the big blue Compile button you see a box which Drop .inc files here
  4. Then press Compile and Download

API top

Well, not much things to say. Everything is well documented inside weaponbox_api.inc

PHP Code:


#if defined _weaponbox_api_included
    #endinput
#endif
#define _weaponbox_api_included

enum /* Functions that can be hooked */
{
    CreateNamedEntity,
    CWeaponBoxHasWeapon,
    CWeaponBoxKill,
    CWeaponBoxPackWeapon,
    CWeaponBoxPackAmmo
}

/**
 *  Calls CWeaponBox functions.
 *  
 *  Can call:
 *  -> CreateNamedEntity Creates an weaponbox entity
 *     @param CreateNamedEntity The function to hook
 *
 *  -> CWeaponBoxHasWeapon Check if an weaponbox entity contain a specific item
 *    @param CWeaponBoxHasWeapon The function to hook 
 *    @param WeaponBoxEntity     The weaponbox entity
 *    @param Item           The item to check
 *
 * -> CWeaponBoxKill Kill an weaponbox entity. 
 *    @param CWeaponBoxKill    The functionTo hook
 *    @param WeaponBoxEntity    The weaponbox entity to remove
 *
 * -> CWeaponBoxPackWeapon Add a specific item into an weaponbox entity 
 *     @param CWeaponBoxPackWeapon The function to hook 
 *    @param WeaponBoxEntity        The weaponbox entity 
 *    @param Item            The item to add inside weaponbox entity
 *    @param ApplyModel        1 if you want to let Core plugin to automatically set proper model. 0 otherwise
 *
 * -> CWeaponBoxPackAmmo Add ammo for an intem inside an weaponbox entity 
 *    @param CWeaponBoxPackAmmo The fucntion to hook
 *    @param WeaponBoxEntity      The weaponbox entity
 *    @param Item          The item for which you want to add ammo
 *    @param Count          The ammo that you want to add
 *
 * All functions return 0 on failure, 1 otherwise.
 */

native WeaponBoxCallFunc(any:...);

/**
 *  Hook Touch between a weaponbox entity and another ent
 *  
 * @param CallBack The function that will be called on touch
 * @param Entity   The entity for which we should hook touch
 * @param Post     Pre(0)/Post(1) forward. Default Pre
 */
native WeaponBoxHookTouch(const CallBack[], const Entity[], Post = 0); 


Basically, you can use two natives.

• WeaponBoxCallFunc
  • Call a specific weaponbox function.
  • Params for each function are explained inside include file.
• WeaponBoxHookTouch
  • Hook touch between weaponbox entity and another
  • Params are explained inside include file.

I feel like providing a plugin example is the best way to explain how this natives work:

/* Plugin generated by AMXX-Studio */

#include <amxmodx>
#include <orpheu>
#include <hamsandwich>
#include <fakemeta>
#include <weaponbox_api>

new WeaponBox 
new  const m_rgpPlayerItems_CBasePlayer[6] = {367, 368, ... }

public plugin_init() 
{
    register_clcmd("CreateWeaponBox", "ClientCommand_CreateWeaponBox")
    register_clcmd("KillWeaponBox", "ClientCommand_KillWeaponBox")
    register_clcmd("CheckForWeapon", "ClientCommand_CheckForWeapon")
    
    //Hook touch
    //Hook for player
    WeaponBoxHookTouch("CWeaponBoxTouch", "player", false)//hook a touch forward as pre
    
}

public ClientCommand_CreateWeaponBox(id)
{
    WeaponBox = WeaponBoxCallFunc(CreateNamedEntity) //create weaponbox entity
    ExecuteHamB(Ham_Spawn, WeaponBox)//spawn it
    
    //Set some origins so we can touch it later
    new Origin[3]; get_user_origin(id, Origin, 3)
    new Float: FOrigin[3]; IVecFVec(Origin, FOrigin)
    
    engfunc(EngFunc_SetOrigin, WeaponBox, FOrigin)
    
    
    new Weapon = get_pdata_cbase(id, m_rgpPlayerItems_CBasePlayer[1])//retrieve a primary weapon from player
    WeaponBoxCallFunc(CWeaponBoxPackWeapon, WeaponBox, Weapon, 1)//add this to weaponbox
    WeaponBoxCallFunc(CWeaponBoxPackAmmo, WeaponBox, Weapon, 32)//set ammo for it
}

public ClientCommand_KillWeaponBox(id)
{
    //No need to call it at Roundend()
    //Game already remove all weaponbox ents when needed
    WeaponBoxCallFunc(CWeaponBoxKill, WeaponBox)//kill an weaponbox function
}

public ClientCommand_CheckForWeapon(id)
{
    new Weapon = get_pdata_cbase(id, m_rgpPlayerItems_CBasePlayer[2])//let's get a secondary weapon from player
    if(WeaponBoxCallFunc(CWeaponBoxHasWeapon, WeaponBox, Weapon))//check if weaponbox already contain this weapon
    {
        client_print(id, print_chat, "It  has same weapon type.")
    }
    else 
    {
        client_print(id, print_chat, "It doesn't have already same weapon type.")
    }
    
}

//Touched is weaponbox entity
//Toucher is the entity that touched the weaponbox
public CWeaponBoxTouch(Touched, Toucher)
{
    //do stuffs
}

Every line is well commented. You need to get item index from a player weapon slot, you can do that by using:
new const m_rgpPlayerItems_CBasePlayer[6] = {367, 368, ... }
get_pdata_cbase
XO_CWeaponBox = 4
Note that if item is invalid it will return -1, not 0.

Credits top

• Bos93
• ConnorMcLeod
• Arkshine

ChangeLog top

• V 0.1:
  • Initial release

[Kia]

Sexy. Good job, may come handy in future mods.

[Arkshine]

ZIP file should be preferred before all, as more generic. No reason to use TAR.GZ here.

It's always welcomed to see new API, but I'm not sure to get the usefulness of this one, since the original code without this API is already quite short & straight. You're wasting more CPU/memory comparing what the API can offer really, which is the same level as making basic stock/macro. Unless you provide something unique, and some more complexity where an API would be welcomed, this would be likely pointless. Also The first native design may not the best idea, it's unsafe and not really user-friendly. Ideally you should have one native per functions so you control more safely the data type passed.

[HamletEagle]

Originally Posted by Arkshine ZIP file should be preferred before all, as more generic. No reason to use TAR.GZ here. It's always welcomed to see new API, but I'm not sure to get the usefulness of this one, since the original code without this API is already quite short & straight. You're wasting more CPU/memory comparing what the API can offer really, which is the same level as making basic stock/macro. Unless you provide something unique, and some more complexity where an API would be welcomed, this would be likely pointless. Also The first native design may not the best idea, it's unsafe and not really user-friendly. Ideally you should have one native per functions so you control more safely the data type passed.

About tar.gz see: https://forums.alliedmods.net/showpo...74&postcount=3
Well, the base idee was that remaking original code is not very easy for everyone, and to have a somehow direct way of doing it is nice and welcomed.
About an year ago I found myself in the position of needing some way to work with weaponboxes and remaking original code was not an option to me, I was looking and game code and asking myself "WTF is this?". I think that this is not a unique case.
About complexity, I don't see what can be added in here(maybe a native to disable the hook and one to get some weaponbox proprieties). If you have suggestions I would be more than happy to hear and to implement them.

[Arkshine]

I know about Tar.gz, that's why I said PREFERRED, because it's more generic. I would use others formats if the ZIP compression would not be enough to hold the forum limit. You see well this format is rarely used here unless for some situations. Tell me, what is your reasons using this format? If none, you would make happy and others users to use the ZIP format.

About plugin I'm not sure to understand what code you're talking about because what you did, it's about just getting the OrpheuFunc of each concerned functions, and hooking the needed forwards. There is no developed code or something.

OrpheuGetFunction "CREATE_NAMED_ENTITY"
OrpheuGetFunction "HasWeapon"
OrpheuGetFunction "PackWeapon"
OrpheuGetFunction "PackAmmo"

register_touch("weaponbox", "*", _

Kill not needed, first could be replaced eventually by cs_create_entity.
Why did you redo HasWeapon for windows?

And that's all basically, if I'm right. There almost no code involded.
An API is way overkill for just that IMO. You could have done the same with macros.
An API is not meant to be just some fast helpers or lazy wrappers, it has to offer something, some control over some functionality.

[HamletEagle]

Well, that was the reason. See, when a moderator tells you to fallow a rule, yo do it.
I was talking about the posibility of redoing game code as you said in your first post, at a point where I didn't know orpheu/okapi and how to search functions, make singatures and so on. Redoing the code was impossible for me that time, maybe this is the case for more users and some easy to use natives will be ok.
In other words, some coders have no idee how to reacreate the code from weapons.cpp, this can help them.

Wanted to add support for 1.8.3 too, but I forgot to do it.

I have explained inside sourecode, HasWeapon is integrated in PackWeapon for windows, maybe someone want to use it just to check if a weapon is in weaponbox.

An API is not meant to be just some fast helpers or lazy wrappers, it has to offer something, some control over some functionality.

Yes, it gave you control over WeaponBox functions. I don't get why you say redoing code manually or hooking functions directly is the same things. In first case you call a huge number of natives, and this can't be compared with calling only one native.

[Arkshine]

Let's try again.

Well, that was the reason. See, when a moderator tells you to fallow a rule, yo do it.

My comment was not to point you were using a wrong format, but that you COULD and SHOULD use a GENERIC format, ZIP by default, before all, as it's more commonly used. This is just for the sake of the users, it's not against you.

I was talking about the posibility of redoing game code as you said in your first post, at a point where I didn't know orpheu/okapi and how to search functions, make singatures and so on. Redoing the code was impossible for me that time, maybe this is the case for more users and some easy to use natives will be ok.

I understand, but what you do, considering how short is the original code (which is almost only about initializing stuffs), would be the same as posting a tutorial about showing the original code without having the extra CPU/Memory. If to make only wrappers, it's more appropriate to use macro/stock and posting in Tutorial.

have explained inside sourecode, HasWeapon is integrated in PackWeapon for windows, maybe someone want to use it just to check if a weapon is in weaponbox

Yes, but the original function still exists, and you can call it. It matters only if you want to hook this function.
It's tricky to get signature for this one, as it's short and has the same model as another one for player.
It should be

00 90 90 90 90 90 90 90 53 55 56 8B ? ? ? 57 8B ? 8B ? 8B ? FF

and it needs +8 for displacement.

Well, Ham_Touch does the job well. Native allow you to limit the hook to a certain entity, and register_touch can't be hooked as pre or post. I plan to add a native to unregister the hook, and engine doesn't allow you to do that.

It was just an example (doesn't matter engine, or whatever) to show how silly is to make a forward called from the original forward... when you can just have only the original forward. My point is this is overkill. So unless you do stuffs which involves actual code/logic/feature/customization/whatever (and not just initialization), current API makes no sense.

[tousif]

Nice one ;) keep it up

[HamletEagle]

Ah, now I get everything. I guess it's my english fault or idk.

My comment was not to point you were using a wrong format, but that you COULD and SHOULD use a GENERIC format, ZIP by default, before all, as it's more commonly used. This is just for the sake of the users, it's not against you

Yes, I understood. When I'll update will change format to zip file too.

I understand, but what you do, considering how short is the original code (which is almost only about initializing stuffs), would be the same as posting a tutorial about showing the original code without having the extra CPU/Memory. If to make only wrappers, it's more appropriate to use macro/stock and posting in Tutorial.

Ah, you point was that using an entire api for that is overkill, not hooking functions.

Yes, but the original function still exists, and you can call it. It matters only if you want to hook this function. It's tricky to get signature for this one, as it's short and has the same model as another one for player. It should be

Nice to know, this mean we can hook only part of a function by using the displacement field ?

It was just an example (doesn't matter engine, or whatever) to show how silly is to make a forward called from the original forward... when you can just have only the original forward. My point is this is overkill. So unless you do stuffs which involves actual code/logic/feature/customization/whatever (and not just initialization), current API makes no sense.

I realised what you want to say and removed my last sentence, but I guess you saw it before. I was not doing only initialization, but also taking care of models, ammo names...

Kill not needed, first could be replaced eventually by cs_create_entity.

IMO Kill() is needed, maybe someone wants to remove weaponbox entity at some point, before game does that.

At the end, will think what I will do. If I'll post a tutorial about weaponbox entities or leave this here.

[Arkshine]

Ah, you point was that using an entire api for that is overkill, not hooking functions.

No idea why you are saying that, but it doesn't change fact that an API just for wrapping almost no code is overkill.

this mean we can hook only part of a function by using the displacement field

No, you can't hook a part of function. Displacement is just to adjust a position from a start address.
Here since I could not find a short signature from start of the function (because of another similar function), I took some bytes before this function so it matches more easily, then you tell Orpheu to just displace by +8 bytes. In signature, function actually starts to 53.

IMO Kill() is needed

When I said that, I was meant that you can make think a weaponbox to remove it. You don't need really to get Kill function, but I said that only for the original code. It's fine to use Kill anyway.

I was not doing only initialization, but also taking care of models, ammo names...

Your whole API does essentially that:

#include <amxmodx>
#include <orpheu>

new OrpheuFunc:CreateNamedEntityFunc;
new OrpheuFunc:HasWeapon;
new OrpheuFunc:Kill;
new OrpheuFunc:PackWepapon;
new OrpheuFunc:PackAmmo;

public plugin_init()
{
    CreateNamedEntity = OrpheuGetFunction("CREATE_NAMED_ENTITY");
    HasWeapon         = OrpheuGetFunction("HasWeapon"  , "CWeaponBox");
    Kill              = OrpheuGetFunction("Kill"       , "CWeaponBox");
    PackWepapon       = OrpheuGetFunction("PackWeapon" , "CWeaponBox");
    PackAmmo          = OrpheuGetFunction("PackAmmo"   , "CWeaponBox");
    
    RegisterHam(Ham_Touch, "weaponbox", "OnWeaponBoxTouch");
}

public OnWeaponBoxTouch(weaponbox, other)
{
}

MyFunction()
{
    new weaponbox = OrpheuCall(CreateNamedEntity);
    // PackWeapon
    // PackWeapon
    // SetModel
    // Spawn
    // etc.
}

If you try to do the same with your example plugin:

#include <amxmodx>
#include <orpheu>
#include <hamsandwich>
#include <fakemeta>

new OrpheuFunction:CreateNamedEntity;
new OrpheuFunction:HasWeapon;
new OrpheuFunction:Kill;
new OrpheuFunction:PackWepapon;
new OrpheuFunction:PackAmmo;

new WeaponBox;
new const m_rgpPlayerItems_CBasePlayer[6] = {367, 368, ... };

public plugin_init()
{
    CreateNamedEntity = OrpheuGetFunction("CREATE_NAMED_ENTITY");
    HasWeapon         = OrpheuGetFunction("HasWeapon"  , "CWeaponBox");
    Kill              = OrpheuGetFunction("Kill"       , "CWeaponBox");
    PackWepapon       = OrpheuGetFunction("PackWeapon" , "CWeaponBox");
    PackAmmo          = OrpheuGetFunction("PackAmmo"   , "CWeaponBox");
    
    register_clcmd("CreateWeaponBox", "ClientCommand_CreateWeaponBox");
    register_clcmd("KillWeaponBox"  , "ClientCommand_KillWeaponBox");
    register_clcmd("CheckForWeapon" , "ClientCommand_CheckForWeapon");
    
    RegisterHam(Ham_Touch, "weaponbox", "OnWeaponBoxTouch");
}

public ClientCommand_CreateWeaponBox(id)
{
    WeaponBox = OrpheuCall(CreateNamedEntity)
    ExecuteHamB(Ham_Spawn, WeaponBox);

    new origin[3], Float: forigin[3];
    get_user_origin(id, origin, 3); IVecFVec(origin, forigin);
    
    engfunc(EngFunc_SetOrigin, WeaponBox, forigin);
    engfunc(EngFunc_SetModel , WeaponBox, "model");
   
    new weapon = get_pdata_cbase(id, m_rgpPlayerItems_CBasePlayer[1]);
    OrpheuCall(PackWepapon, WeaponBox, weapon);
    OrpheuCall(PackAmmo, WeaponBox, weapon, 32);
}

public ClientCommand_KillWeaponBox(id)
{
    OrpheuCall(Kill, WeaponBox);
}

public ClientCommand_CheckForWeapon(id)
{
    new weapon = get_pdata_cbase(id, m_rgpPlayerItems_CBasePlayer[2]);
    client_print(id, print_chat, OrpheuCall(HasWeapon, WeaponBox, weapon) ? "It  has same weapon type." : "It doesn't have already same weapon type.");
}
public OnWeaponBoxTouch(weaponbox, other)
{
}

It's basically the same. Do you still think a whole API is necessary for just that?

I don't mind an API around WeaponBox, but it's needed to be more than just direct call to original game functions. Probably a lot you can do around weaponbox, you could handle existing one too.