clobberxd / gunslinger

[alpha] One of the most realistic ranged weapons mod for Minetest. Consists of a gun-registration API and a comprehensive arsenal of builtin guns.

Gunslinger

Gunslinger is a ranged weapons API that allows mods to add realistic and enjoyable guns to Minetest. A variety of different guns are provided with the mod, and can be disabled if required (see Settings).

License

• Code: MIT
• Media: CC0

Settings

• gunslinger.lite [bool] (defaults to false)
  • Toggles lite mode
• gunslinger.disable_builtin [bool] (defaults to false)
  • Disables builtin guns - only the API will be provided.
  • Useful if mods/games provide custom guns.

Architecture

Type inheritance

Gunslinger makes use of gun types in order to ease registration of similar guns. A type is made up of a name and a table of default values to be applied to all guns registered with that type. Types are optional, and can also be omitted altogether. Guns are allowed to override their type defaults, for maximum customizability.

Ammo

Each type/gun needs to be associated with ammo (registered using gunslinger.register_ammo). If a weapon definition doesn't explicitly define the appropriate field, it will be automatically linked with the default ammo provided by Gunslinger.

Projectile Engine

Gunslinger uses the term "Projectile Engine" to refer to the code that handles the tracking and control of fired projectiles. Once a projectile hits a target, the damage to the target is equivalent to:

base_dmg * def.dmg_mult (base damage * gun's damage multiplier)

TODO: The default damage handling would be overridable by using on_hit callbacks. If a gun specifies an on_hit callback, the default damage code would be ignored.

Progressive Raycast

Progressive Raycast is the default projectile engine of Gunslinger. It technique works by simulating the movement of a projectile along its trajectory every server step. Once a target is hit by a projectile, the default damage code is run.

Automatic guns

gunslinger supports automatic guns out of the box, while not causing excessive lag. Nevertheless, disabling automatic guns (by enabling lite mode) is recommended on large public servers as it would still cause quite a bit of lag, in spite of this optimization.

Lite mode

Enabling lite mode will disable the non-essential features which are potentially lag-inducing. Recommended for large public servers.

Note: As of now, enabling lite mode will only disable automatic guns, but there are plans to allow lite mode to disable much more.

API Documentation

See API.md for the complete gunslinger API documentation, including the main API methods, internal and helper methods, data structures, etc.

gunslinger's Issues

Add support for weapon add-ons like scopes, suppressors, and extended mags

Improve textures (incl. builtin guns, ammo, etc.)

I am terrible at texturing, and it'd be great if someone else can provide improved textures for

• Ammo
• Builtin gun(s).

(Ab)use stack count display in item slots to display size of clip

This is actually a great way to display the size of the clip, but requires handling a lot of scenarios, including item drop, item pick-up. Handling item pickup requires a callback - there's a PR in MT, but it hasn't been merged just yet. Once that PR has been merged, I think this feature would be doable.

Ammo is still non-existent

Textures are the probably the only thing that makes me hesitant about implementing this "feature". I'll just use a dummy texture at the moment, and get this done. Proper textures is still a must for v1.0.0 anyway (#14).

(Ab)use HUD elements to the maximum

There's a lot of scope (no pun intended) for using HUD elements in gunslinger, like:

• [Remaining ammo / Clip-size] indication
• Better crosshairs (Maybe replace builtin crosshair element with scope overlay when aiming down sights?)
• Damage numbers
• (Lots more!)

Add more builtin guns

Builtin guns are provided for proof of concept, and this means the arsenal of builtin guns needs to be more complete. The following are the minimum requirements for builtin guns for v1.0.0:

• Assault rifle
• Pump-action shotgun
• Fancy gun that uses only burst mode
• Pistol
• Bolt-action rifle (Technically isn't a sniper rifle until settable player FOVs is a thing)

Walking + Firing = Self Shooting

If you walk forward and fire a weapon at the same time you shoot yourself. Is it possible to ignore the shooter when checking for hit objects or can the ray begin a bit further in front of the shooter?...

Fix credits

Personal reminder to check the credits and attributions before release.

Trigger callbacks when projectile hits a target

Thinking of an on_hit callback in the gun definition like what shooter has implemented...

Headshot detection code assumes that the target is a player with the MTG character model, which is very bad. Such hard-coded stuff should be removed from the API, and should be re-implemented using this callback.

Duplication Glitch

If you click to reload and then scroll to another slot in the hotbar, that slot will be populated with a new gun of the type you are reloading...

Use deferred raycast to accurately replicate behaviour of projectile entity

Using entities would allow projectiles to be much more realistic in terms of the time taken to hit the target. Since entities aren't used at all for the moment, the projectiles insta-reach the target, which makes gun-fighting way too easy and OP.

But it could be possible to replicate the behaviour of projectile entities without using entities, by implementing the method of "deferred raycast", which works like so:

• Immediately perform a raycast on_lclick.
• Calculate time taken for projectile to intercept a target if it exists.
• Re-run the raycast after the calculated time.
  • The second raycast is the one that actually informs the mod whether a target exists or not.
  • The first raycast only serves the purpose of calculating the amount of time for the second raycast to be delayed by.

Convert to modpack; add builtin guns as separate mod

This makes it more straight-forward to disable builtin guns if required.

Crash on shoot

When I left-click the game crashes and I get this error

AsyncErr: ServerThread::run Lua: Runtime error from mod 'gunslinger' in callback item_OnUse(): ...64\minetest-5.2.0-win64\bin\..\builtin\common\vector.lua:118: attempt to perform arithmetic on field 'x' (a nil value)
stack traceback:
	...64\minetest-5.2.0-win64\bin\..\builtin\common\vector.lua:118: in function 'multiply'
	...in64\minetest-5.2.0-win64\bin\..\mods\gunslinger/api.lua:51: in function 'get_pointed_thing'
	...in64\minetest-5.2.0-win64\bin\..\mods\gunslinger/api.lua:232: in function 'fire'
	...in64\minetest-5.2.0-win64\bin\..\mods\gunslinger/api.lua:326: in function <...in64\minetest-5.2.0-win64\bin\..\mods\gunslinger/api.lua:309>

Entity-based projectiles is inevitable...

While gunslinger uses Deferred Raycasting for improved realism without much of a performance hit, there are still some potential inconsistencies or edge-cases like the one below:

Deferred Raycasting works by initially performing a raycast to obtain the distance to the point being aimed at. If the player in the screenshot is moving, the shooter has to compensate for the player's movement by shooting ahead of the player. But due to the position and angle of the shooter, the initial dummy raycast will return a pointed_thing pointing to a very distant node. This results in the delay being wrongly calculated, which means that the second and actual raycast will be performed after a wrongly-calculated delay, making this technique worse than instant-hit.

As much as I hate it, gunslinger would have to start using entity-based projectiles, for the sake of consistency. :|

Add support for manual reloading

It's natural to want to manually reload when not firing, even if the clip isn't fully empty. This currently isn't possible. It's also a little lag-inducing to check for key-presses (not to mention, MT doesn't detect more than a couple of keys).

Requires changes in MT to be implementable.

Split shotgun-style fire (`splash`) from `mode`

All the other values of the mode field have something to do with number of rounds fired. But splash is more about the number of pellets fired in a single round, and has nothing to do with mode.

Use Progressive Raycasting instead of Deferred Raycasting.

This is similar to how shooter manages to process rounds without issues like in #25. See #25 (comment) to know how this works.

Once I can understand this technique better, I'll definitely give this a try. If this works, I'd definitely go with this over an entity-based approach.

Using os.time() does not provide millisecond precision

Issue

os.time is primarily used to calculate the minimum time difference of two consecutive shots. This interval can (and is generally) between 0 and 1 for guns of medium to high rate of fire. But since os.time doesn't support millisecond precision, the resultant fire rate becomes 1 second.

Possible fix

globalstep. The dtime param passed to the globalstep provides the precision required for this job. I prefer to not use a globalstep for this purpose, but there doesn't seem to be another way.

Implement weapon inaccuracy

Implement inaccuracy, and implement increased accuracy when aiming down sights. This feature would replace the lame 20% additional damage when aiming down sights.

• Spread (f4cdc15)
• Recoil (7999179)
• Bullet drop

Add support for weapon perks

Add support for unique effects and perks, per-gun. Perks are essentially optional special effects of guns that are activated when their bullets hit targets.

Examples

• Speed boost
• HP regen
• "Incendiary" bullets that sets players on fire; player continues to take damage for the next x seconds after being hit by the bullet(s).

Implementation details

• Perks should be registered by using gunslinger.register_perk.
• Effects / Properties of perk should be customizable.
• A gun can register at most one perk, either directly or in its type def.
• During registration, perks should be registered by passing a table containing:
  • Name of perk.
  • Optional properties of perk.

Automatic guns can "reload" twice

This doesn't seem to be a simple fix, so I'm creating an issue to not forget about it.

Play sounds on more events

Sounds could also be used/added for

• Out of ammo (Implemented, but no default sound)
• Reloading
• Manual loading
• Toggling scopes (probably overkill)