Ammo Mod: Firearms & Caliber System (WIP)

Ammo Mod adds a modular firearm and ammunition system for Voyage worlds. It is designed for survival, horror, modern, tactical, military, post-apocalyptic, or firearm-heavy settings where ammunition should matter. (41 Weapon preset) The mod adds: - firearm items with distinct combat roles; - caliber-based ammunition; - ammo boxes that add ammo to the correct reserve; - scripted direct ammo tracking; - fire mode rules; - weapon profiles for combat behavior; - an expandable template for adding new weapons. This mod does not use magazines, chamber states, or reload simulation. Weapons consume compatible ammunition directly from the hidden Ammo Mod reserve. If the correct ammo reaches 0, the weapon cannot fire. Example: - MP5 uses Loose 9mm Rounds. - AK-74M uses Loose 5.45x39mm Rounds. - RSASS uses Loose 7.62x51mm Rounds. - Shotguns use 12 Gauge Shells. Core Rules 1. Direct Ammo Tracking Each weapon consumes only the ammo type listed in its Ammo Mod profile: ammoKey / ammoName. Wrong caliber or wrong ammo type never works. 2. Fire Modes The mod supports different fire modes by weapon type: - single shot = 1 round; - double tap = 2 rounds; - short burst = 3 rounds; - controlled burst / unspecified burst = 5 rounds; - long burst = 10 rounds; - spray / suppressive fire / holding the trigger = heavy automatic fire only if the weapon supports it. Semi-automatic weapons cannot fire automatic bursts unless their profile says so. Shotguns usually fire one shell per shot. Marksman weapons favor careful single shots and precise follow-up shots. 3. Weapon Profiles Each weapon has narrative combat parameters: - role; - damage; - range; - accuracy; - recoil; - armorPenetration; - handling; - noise; - reliability; - combatNote. These are not exact numerical stats. They guide the AI when resolving combat, so pistols, SMGs, rifles, marksman rifles, shotguns, and heavy weapons feel different. 4. Ammo Boxes Ammo boxes add ammunition to the matching reserve and should be treated as consumed or emptied when used. Examples: - Box of 9mm Rounds adds Loose 9mm Rounds. - Box of 5.45x39mm Rounds adds Loose 5.45x39mm Rounds. - Box of 12 Gauge Shells adds 12 Gauge Shells. How to Add a New Weapon To add a weapon: 1. Add the weapon item. 2. Add or reuse the correct ammo item. 3. Add an ammo box if needed. 4. Add one weapon profile block in the Ammo Mod triggers. Weapon Item Template: "Weapon Name": { "name": "Weapon Name", "category": "Weapon", "description": "Describe appearance, role, strengths, weaknesses, firing behavior, and which Ammo Mod ammunition it consumes.", "bonuses": [], "slot": "", "mediaContent": "" } Ammo Item Template: "Loose Caliber Rounds": { "name": "Loose Caliber Rounds", "category": "Ammo", "description": "Describe the caliber itself: damage, recoil, penetration, range behavior, and combat properties. Do not tie it to only one weapon.", "bonuses": [], "slot": "", "mediaContent": "" } Weapon Profile Template: storage.ammo_mod_config.weapons['Weapon Name'] = { key: 'unique_weapon_key', type: 'semiAuto', caliber: 'Caliber Name', ammoKey: 'ammo_key_here', ammoName: 'Loose Ammo Item Name', startingAmmo: 0, aliases: ['alias 1', 'alias 2'], role: 'weapon role', damage: 'low / medium / high / very high', range: 'close / close-mid / mid / mid-long / long', accuracy: 'low / medium / high / very high', recoil: 'low / medium / high / very high', armorPenetration: 'none / low / medium / high / very high', handling: 'slow / medium / fast', noise: 'quiet / moderate / loud / very loud', reliability: 'poor / medium / high / very high', combatNote: 'Short combat behavior note.' }; if (storage.ammo_mod_state.ammo_key_here === undefined) storage.ammo_mod_state.ammo_key_here = 0; Recommended weapon types: - semiAuto: pistols, semi-auto carbines, semi-auto rifles; - automatic: SMGs, assault rifles, machine guns; - marksman: DMRs, sniper rifles, precision rifles; - shotgun: shotguns. Important: - Use startingAmmo: 0 by default. - Weapons should not give ammo when found. - Ammo is added only through ammo boxes, loot, story rewards, or explicit Ammo Mod supply triggers. - If two weapons share the same ammoKey and ammoName, they use the same ammo reserve. - Do not add magazine mechanics unless using a separate magazine add-on. - Ammo descriptions should describe the caliber, not one specific weapon. Ammo Mod should be treated as authoritative for firearm actions. If a trigger states shots fired and ammo remaining, the narrator should obey it exactly. Do not invent spare ammo, hidden magazines, free reloads, extra shots, or wrong-caliber compatibility.