RaihanPrnwd/samp-weapon-utils

weapon_utils.inc - SA-MP Weapon Utilities Include

---

Powerful, easy-to-use Pawn include for weapon systems on SA-MP.
Simple integration, complete functionalities, zero hassle.
Beginner-friendly & advanced-ready.

---

📦 About

weapon_utils.inc provides a comprehensive set of macros and functions for managing weapons in your San Andreas Multiplayer (SA-MP) script.
Plug-and-play: just #include <weapon_utils> and get instant access to reliable functions for giving, managing, querying, restricting, and listing weapons.

• Bahasa Indonesia:
  weapon_utils.inc adalah include PAWN praktis untuk sistem senjata SA-MP.
  Semua fungsi siap pakai, mudah digunakan & diintegrasikan, cocok untuk semua scripter (pemula/lanjutan).

---

🚀 Features

• 📥 Super-simple import:
  #include <weapon_utils>
• 🔫 Give/Remove weapons & ammo
• ♻️ Reset all weapons / specific slots
• 📦 One-call weapon pack (hunting / police / full)
• 📋 Get weapon info: weaponid, slot, name, ammo, category & emoji
• 🚫 Banned/Allowed weapon system
• ⚖️ Set requirement: minimum player level for weapon
• 💾 Store/load weapon inventory to array/string (for DB)
• 🛡️ Built-in anti-cheat & security helper
• 📝 List & Find weapon by name/ID
• 🥇 No heavy dependencies (only a_samp)

---

🛠️ Installation

1. Copy weapon_utils.inc to your pawno/include/ directory.
2. Add this to your script source:

   #include <weapon_utils>
   

3. Compile and enjoy!

---

📚 Main Functions

Basic Management

Weapon Packs (Example Set)

• GiveHuntingPack(playerid) → Give hunting pack (Shotgun, Rifle, Pistol)
• GivePolicePack(playerid) → Give police pack (Bat, Deagle, MP5, M4, Spraycan, etc.)
• GiveFullWeaponPack(playerid) → All weapons with ammo (superadmin use)

Weapon Info

• GetWeaponNameEx(weaponid, dest[], len) - Get full weapon name by id
• WeaponShortName(weaponid) - Get short weapon name (abbreviation)
• GetWeaponCategory(weaponid, dest[], len) - Get weapon category/type (e.g., SMG, Shotgun)
• GetWeaponIcon(weaponid, dest[], len) - Get icon/emoji for weapon

Restriction, Ban, & Requirement

• BanWeapon(weaponid) - Ban/block a weapon from being given
• AllowWeapon(weaponid) - Unban a weapon
• AllowAllWeapons() - Unban all weapons
• BanAllWeapons() - Ban all weapons (except fist)
• IsWeaponBanned(weaponid) - Check if weapon is banned
• SetWeaponMinLevel(weaponid, level) & GetWeaponMinLevel(weaponid)
  • Set/get minimum level required for using weapon

Save/Load & Database Helpers

• SavePlayerWeapons(playerid, weaponArr[], ammoArr[]) - Save weapon array
• LoadPlayerWeapons(playerid, weaponArr[], ammoArr[]) - Load weapon array
• WeaponsToString(playerid, str[], len) - Serialize weapons for DB
• StringToWeapons(str[], weaponArr[], ammoArr[]) - Parse DB weapon string

Miscellaneous

• DetectWeaponCheat(playerid) - Detect sudden weapon/ammo changes
• PrintAllWeapons(playerid) - Output full weaponlist to player
• FindWeaponIDByShortName(name[]) - Get weaponid by partial/short name
• ListPlayerWeapons(playerid, weaponArr[], ammoArr[]) - Get all current weapons
• RemoveBannedWeapons(playerid) - Remove all banned weapons from player

Macros

• MAX_WEAPON_SLOTS (default: 13)
• MAX_WEAPON_ID (default: 46)
• WEAPONNAME_SHORT(%1) (macro for short weapon name)

---

💡 Usage Tips

• Combine with level/player/mission system to restrict/unlock weapons.
• For commands using weapon name (e.g. /give [name]), use FindWeaponIDByShortName.
• Use RemoveBannedWeapons(playerid) in OnPlayerSpawn (for security).
• Store/load inventory for custom DB handling (arrays/strings).
• Free to modify/extend, but keep credit to author is REQUIRED.

---

🧑‍💻 Example Usage

public OnPlayerCommandText(playerid, cmdtext[])
{
    if(strcmp(cmdtext, "/myweapons", true) == 0)
    {
        PrintAllWeapons(playerid);
        return 1;
    }
    if(strcmp(cmdtext, "/giveak", true) == 0)
    {
        GiveWeapon(playerid, 30, 150); // AK47 (id:30), 150 ammo
        return 1;
    }
    return 0;
}

---

🙏 Credits

• Script & Docs: Raihan Purnawadi (github.com/RaihanPrnwd)
• Weapon categories & icon/emoji suggestions inspired by GTA/SA-MP defaults.

---

📖 License

Bebas digunakan/ubah/bagikan dengan kredit wajib.
(Free to use/edit/share, CREDIT IS REQUIRED.)

---

✨ Terima kasih! / Thank You!

Terima kasih telah memakai weapon_utils.inc untuk server/script Anda.
Selamat berkarya & sukses untuk projek Anda!

Thank you for using weapon_utils.inc for your script/server!
Happy coding & good luck with your project!

---