ModularShoot
ModularShoot is an attribute-driven, modular assembly gun system framework mod for NeoForge 1.21.1.
Framework only: This mod provides registration APIs, an attribute calculation pipeline, and a shooting engine. It ships with zero built-in guns, zero built-in plugins, and zero built-in traits. All content is added by other mods via the API or datapacks.
Key Features
| Feature | Description |
|---|---|
| Single ID + DataComponent | All guns share a single item ID (modularshoot:gun), differentiated via DataComponent. Same for plugins (modularshoot:plugin) |
| Pure Framework | 0 preset guns, 0 preset plugins, 0 preset traits — only API and engine |
| Attribute-Driven | Gun behavior is entirely determined by attributes + traits. No hardcoded logic. ADD_VALUE → ADD_MULTIPLIED_BASE → ADD_MULTIPLIED_TOTAL three-stage stacking |
| Dual Registration | Supports Java API registration and datapack JSON registration, sharing the same registries. /reload hot-reloads JSON; API entries are unaffected |
| Non-Entity Bullets | Bullets are lightweight data records managed by BulletManager, supporting thousands of simultaneous projectiles (chunk-bucketed indexing + capsule collision) |
| Fully Event-Driven | All extension points exposed via events + callback APIs: shoot events, install/uninstall events, trait hooks, damage handlers, right-click/reload events |
| Server-Authoritative | Shooting, bullet flight, and hit detection are all server-side. Client is render-only, cheat-resistant |
Quick Navigation
| Doc | For | Content |
|---|---|---|
| API Reference | Devs calling framework functions in code | Quick-reference tables for all ModularShootAPI public methods |
| Registry Reference | Devs understanding definition fields | All 6 dynamic registries and field details for each definition type |
| Datapack Registration | Devs using JSON to register content | Datapack JSON file paths, fields, and format reference |
| Command Reference | Devs using debug commands | /modularshoot subcommand quick reference |
| Examples | Devs wanting to see code directly | All Java API and JSON examples in one place |
6 Framework Registries
| Registry ID | Purpose | Registration Method |
|---|---|---|
modularshoot:guns | Gun definitions | Java API / Datapack JSON |
modularshoot:plugins | Plugin definitions | Java API / Datapack JSON |
modularshoot:plugin_types | Plugin type (category) definitions | Java API / Datapack JSON |
modularshoot:traits | Boolean trait definitions | Java API / Datapack JSON |
modularshoot:states | Persistent state definitions | Java API / Datapack JSON |
modularshoot:attribute_meta | Attribute metadata (defaults, display info, bindings) | Datapack JSON |
Attribute bodies (
Attributeinstances) must be registered using vanillaDeferredRegisterintoBuiltInRegistries.ATTRIBUTE. They are not in the dynamic registries above.
Preset Attributes
The framework pre-registers 9 numeric attributes (modularshoot namespace):
| Attribute ID | Description | Default |
|---|---|---|
hit_damage | Damage per hit | 1.0 |
fire_rate | Shots per second (cap 20, ≤0 disables shooting) | 1.0 |
range | Max bullet flight distance (blocks) | 50.0 |
accuracy_yaw | Horizontal spread angle (degrees) | 10.0 |
accuracy_pitch | Vertical spread angle (degrees) | 10.0 |
entity_penetration | Entities penetrated (0 = no penetration) | 0 |
bullet_speed | Bullet flight speed (blocks/sec) | 20.0 |
bullet_size | Bullet collision sphere radius (0 = raycast) | 0.5 |
block_penetration | Blocks penetrated (0 = no penetration) | 0 |
Key Events Overview
| Event | Fires When | Cancellable |
|---|---|---|
PreShootEvent | After shoot conditions pass | Yes |
PostShootEvent | After bullet is registered | No |
GunRightClickEvent | Right-click gun outside GUI | Yes |
ReloadEvent | Reload key pressed (default R) | Yes |
PrePluginInstallEvent | After install validation passes | Yes |
PostPluginInstallEvent | After plugin written to component | No |
PrePluginUninstallEvent | Before plugin removal | Yes |
PostPluginUninstallEvent | After plugin removed | No |