{"id":51847070,"url":"https://github.com/alavesa/guns-plugin","last_synced_at":"2026-07-23T14:01:54.068Z","repository":{"id":369153495,"uuid":"1288635760","full_name":"alavesa/guns-plugin","owner":"alavesa","description":"Config-driven custom guns for Paper: in-game create/edit (damage, fire rate, name, model), crossbow aiming pose, hitscan shots.","archived":false,"fork":false,"pushed_at":"2026-07-21T17:51:30.000Z","size":191,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-21T18:16:07.357Z","etag":null,"topics":["guns","minecraft","minecraft-plugin","paper-plugin"],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/alavesa.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-07-03T20:00:24.000Z","updated_at":"2026-07-21T17:53:09.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/alavesa/guns-plugin","commit_stats":null,"previous_names":["alavesa/guns-plugin"],"tags_count":37,"template":false,"template_full_name":null,"purl":"pkg:github/alavesa/guns-plugin","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alavesa%2Fguns-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alavesa%2Fguns-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alavesa%2Fguns-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alavesa%2Fguns-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alavesa","download_url":"https://codeload.github.com/alavesa/guns-plugin/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alavesa%2Fguns-plugin/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35804545,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-07-20T02:08:10.276Z","status":"online","status_checked_at":"2026-07-23T02:00:06.683Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["guns","minecraft","minecraft-plugin","paper-plugin"],"created_at":"2026-07-23T14:01:53.363Z","updated_at":"2026-07-23T14:01:54.054Z","avatar_url":"https://github.com/alavesa.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Guns — config-driven custom guns for Paper\n\n[![Reviewed by PatchPilots](https://img.shields.io/badge/Reviewed%20by-PatchPilots-8A2BE2)](https://github.com/alavesa/patchpilots)\n\nCustom guns **and grenades** for Paper servers: define them in `guns.yml` or create and edit\nthem **in-game**, each with its own name, damage, fire rate, range, magazine, reload time,\nsound and resource pack model — plus **backstab bonus damage**, **bleed/poison hit effects**\nand **ricocheting bullets**. Guns are held in the **crossbow aiming pose** (they're\npre-charged crossbows under the hood — vanilla firing is fully cancelled and replaced with\ninstant raytrace shots).\n\n## Install\n\nDrop `Guns-x.y.z.jar` into the server's `plugins/` folder and restart. Requires Paper (or\nSpigot) 1.21.4+ and Java 21. No datapack needed.\n\n## Use\n\n- **Shoot**: right-click. Instant hit up to `range` blocks, tracer particles.\n- **Ammo bar**: while a gun is held, a boss bar at the top of the screen shows the gun's name\n  and bullets left (e.g. `Pistol  7 / 12`) as a notched bar that drains and shifts\n  green → yellow → red. It disappears when you put the gun away.\n- **Reload**: press **F** (swap-hands). Takes `reload-ticks`.\n- Out of ammo → click sound + \"press F to reload\".\n\n## Commands (`/guns`)\n\n| Command | What it does | Permission |\n|---|---|---|\n| `/guns list` | list gun + grenade ids | guns.use |\n| `/guns give \u003cid\u003e [player]` | get a gun or grenade | guns.give |\n| `/guns create \u003cid\u003e [gun\\|grenade]` | create with default stats | guns.admin (op) |\n| `/guns edit \u003cid\u003e \u003cstat\u003e \u003cvalue\u003e` | edit a stat | guns.admin (op) |\n| `/guns reload` | reload guns.yml | guns.admin (op) |\n\nGun stats: `name`, `model`, `damage`, `firerate`, `range`, `magazine`, `reloadticks`,\n`sound`, `soundpitch`, `backstab`, `effect`, `effectticks`, `effectlevel`, `ricochet`.\nGrenade stats: `name`, `model`, `power`, `fuseticks`, `velocity`, `breakblocks`.\nStat edits apply **immediately to already-given items** — only `name` and `model` are baked\ninto the item, so re-run `/guns give` after changing those.\n\nExample:\n\n```\n/guns create shotgun\n/guns edit shotgun damage 9\n/guns edit shotgun firerate 0.8\n/guns edit shotgun name \u00266Shotgun\n/guns give shotgun\n\n/guns create sticky grenade\n/guns edit sticky power 4\n/guns edit sticky fuseticks 40\n/guns give sticky\n```\n\n## Combat features\n\n- **Backstab** (`backstab`, multiplier): shots that hit a target from behind deal\n  `damage × backstab`, with a \"Backstab!\" actionbar + crit sound. `1.0` disables it.\n- **Hit effects** (`effect` + `effectticks` + `effectlevel`): `bleed` deals `effectlevel`\n  raw damage per second with blood particles for the duration; any potion effect name\n  (`poison`, `wither`, `slowness`, `glowing`, …) applies that effect at `effectlevel`.\n- **Ricochet** (`ricochet`, bounce count): bullets reflect off blocks with a metallic ping\n  and keep going until they run out of `range` (total across bounces). After the first\n  bounce your own bullet can hit YOU — mind the angles.\n- **Grenades**: vanilla throw arc (snowball); `fuseticks 0` explodes on impact, otherwise\n  the grenade lands, cooks visibly on the ground, then explodes (`power`; TNT is 4.0).\n  Explosions knock back and damage like real ones; `breakblocks` is off by default.\n\n## Resource pack (models) — ready-made in [`resource-pack/`](resource-pack/)\n\nThe repo ships a working resource pack with **placeholder 3D models for every example gun and\ngrenade** (`gun_pistol`, `gun_rifle`, `gun_venom`, `grenade_frag`) — grab\n`GunsResourcePack.zip` from the release, drop it in your `resourcepacks` folder (or serve it\nvia `server.properties` → `resource-pack=\u003curl\u003e`), and the guns show as 3D guns out of the box.\nReplace the placeholders with your own Blockbench models when ready.\n\nHow it's wired: each gun's `model` stat is a `custom_model_data` **string** id on a\n`minecraft:crossbow` item (grenades: `minecraft:snowball`), selected in\n`assets/minecraft/items/crossbow.json` / `snowball.json` (1.21.4+ item model system), pointing\nat models under `assets/guns/models/item/`. Without any pack the guns still work and show as\nloaded crossbows (the aiming pose is a player animation, independent of the model).\n\n**Full step-by-step instructions — in Finnish — in\n[`resource-pack/OHJEET.md`](resource-pack/OHJEET.md)**: plugin install, pack install (personal\nand server-wide), making models in Blockbench, adding them to the pack, and a\ntroubleshooting checklist.\n\nGun sounds accept any namespaced key, so `sound` can point at your resource pack's custom\nsounds (e.g. `guns:shot.pistol` from your pack's `sounds.json`).\n\n## Building\n\n```\nmvn package    # requires JDK 21; jar lands in target/\n```\n\n## Honest notes\n\n- Shots are instant raytraces (hitscan), not projectiles — no travel time or drop.\n- Fire rate is a cap on right-click shots (semi-auto). True hold-to-fire full-auto isn't\n  reliably detectable server-side; if you want it, a \"burst\" stat is the practical route.\n- Damage respects armor/enchants (it goes through the normal damage pipeline, credited to the\n  shooter).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falavesa%2Fguns-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falavesa%2Fguns-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falavesa%2Fguns-plugin/lists"}