gunslinger/API.md

gunslinger API documentation

This file aims to document all the internal and external methods of the gunslinger API.

External API methods

gunslinger.register_type(name, def)

• Registers a type for name.
• def [table]: Gun definition table.

gunslinger.register_gun(name, def)

• Registers a gun with the name name.
• def [table]: Gun definition table.

`gunslinger.register_magazine(magazine, ammunition, size)

• Registers a magazine. note: the gun must have def.magazine = true for it to use them.
• magazine [itemstring] the itemstring of the magazine tool. (it needs to be a tool)
• ammunition [itemstring] the itemstring of the ammunition it is able to hold.
• size [number] the max amount of cartridges the magazine can hold.

gunslinger.get_def(name)

• Retrieves the Gun definition table.

Internal API methods

play_sound(sound, obj)

• Helper function to play object-centric sound.
• sound [SimpleSoundSpec]: Sound to be played.
• obj [ObjectRef]: Origin of the played sound.

add_auto(name, def, stack)

• Helper function to add player entry to automatic table.
• def and stack are cached locally for improved performance.
• name [string]: Player name.
• def [table]: Gun definition table of wielded item.
• stack [itemstack]: Itemstack of wielded item.

show_scope(player, scope, zoom)

• Activates gun scope, handles placement of HUD scope element.
• player [ObjectRef]: Player obj. used for HUD element creation.
• scope and zoom: Gun definition fields.

hide_scope(player)

• De-activates gun scope, removes HUD element.
• player [ObjectRef]: Player obj. to remove HUD element from.

on_lclick(stack, player)

• on_use callback for all registered guns. This is where most of the firing logic happens.
• Handles gun firing depending on their mode.
• [reload] is called when the gun's magazine is empty.
• If mode is "automatic", an entry is added to the automatic table which is parsed by on_step.
• stack [ItemStack]: ItemStack of wielditem.
• player [ObjectRef]: ObjectRef of user.

on_rclick(stack, player)

• on_place/on_secondary_use callback for all registered guns. Toggles scope view.
• stack [ItemStack]: ItemStack of wielditem.
• player [ObjectRef]: ObjectRef of user.

fire(stack, player)

• Responsible for firing one single shot and dealing damage if required. Reduces ammo based on clip_size.
• If gun is worn out, reloads gun in stack if there's ammo in player inventory; else, plays a click sound.
• stack [ItemStack]: ItemStack passed by on_lclick.
• player [ObjectRef]: Shooter player passed by on_lclick.

burst_fire(stack, player)

• Helper method to fire in burst mode. Takes the same arguments as fire.

on_step(dtime)

• This is the globalstep callback that's responsible for firing automatic guns.
• This works by calling fire for all guns in the automatic table if player's LMB is pressed.
• If LMB is released, the respective entry is removed from the table.

Gun Definition table

• itemdef [table]: Item definition table passed to minetest.register_item.

  • Note that on_use, on_place, and on_secondary_use will be overridden.

• ammo [itemstring]: What type of ammo to use when reloading.

• clip_size [number]: Number of bullets per-clip.

• fire_rate [number]: Number of shots per-second.

• range [number]: Range of fire in number of nodes.

• spread [number]: How much bullets will spread away from the cursor.(0 is nothing, 1000 is anywhere in front of the player (I think))

• base_dmg [number]: Base amount of damage dealt in HP.

• pellets [number]: Number of bullets per shot, used for shotguns.

• magazine [boolean]: If the gun's ammo is a magazine, set to true, leave nil or false otherwise.

• vertical_recoil [number]: max amount of moving the players vertical look upwards. the min amount is vertical_recoil/2

• horizontal_recoil [number]: the max amount of moving the players horizontal look side to side. finds a value between horizontal_recoil and -horizontal_recoil.

• mode [string]: Firing mode.

  • "manual": One shot per-click, but requires manual loading for every round; aka Bolt-action.
  • "semi-automatic": One shot per-click.
  • "burst": Multiple rounds per-click. Can be set by defining burst field. Defaults to 3.
  • "automatic": Fully automatic; shoots as long as primary button is held down.
  • "hybrid": Same as "automatic", but switches to "burst" mode when scope view is toggled.

• scope [string]: Name of scope overlay texture.

  • Overlay texture would be stretched across the screen, and center of texture will be positioned on top of crosshair.

• zoom [number]: (WARNING: Unimplemented) Sets player FOV in degrees when scope is enabled (defaults to 0, i.e. no zoom)

  • Requires scope to be defined.

• fire_sound [string]: Name of .ogg sound file without extension. Played on gun-fire.