Module weapon

Weapons functions

Functions

boomstick_api.register_weapon_fire_condition (func) Registers a callback function that allows or denies a player to fire a weapon based on your own custom logic.
boomstick_api.register_projectile_collision (func) Registers a callback function to be called when any projectile has a collision.
boomstick_api.register_weapon_fire (func) Registers a callback function to be called when any projectile has a collision.
boomstick_api.weapon_is_full (item_definition) Returns a boolean for whether a weapon is at maximum capacity (i.e no more ammo will fit).
boomstick_api.weapon_is_empty (item_definition) Returns a boolean for whether or not a weapon is empty (i.e not loaded).
boomstick_api.weapon_is_cocked (item_definition) Returns a boolean for whether or not a weapon is ready to fire.
boomstick_api.fire_weapon (itemstack, user, pointed_thing) Fires a weapon.
boomstick_api.fire_loaded_weapon (weapon_data, user, pointed_thing) Fires a weapon as if it is loaded.
boomstick_api.spawn_smoke_particles (player, particles) Generates smoke particles that look like smoke from a fired weapon Note: It is usually not necesary to call this function directly unless you are extending the mod or making custom behavior.
boomstick_api.fire_empty_weapon (weapon_data, user) Fires a weapon as if it is empty.
boomstick_api.can_load_weapon (inventory_item, ammo_item) Returns a boolean for whether or not a given weapon can be loaded.
boomstick_api.recoil (player, recoil) Pushes the player's view up, simulating recoil.
boomstick_api.knockback (player, recoil) Pushes the player backwards based on recoil.


Functions

boomstick_api.register_weapon_fire_condition (func)
Registers a callback function that allows or denies a player to fire a weapon based on your own custom logic. If you'd like to allow or deny the use of weapons at your discretion, register a function that must return a boolean value. If it returns true, the player can fire their weapon. This is useful for implementing things like 'no guns zones' (for spawn or public areas), or even russian roulette.

Note: This is distinct from a normal callback, in that the callback function is not only called but its return value can affect execution of other code.

Parameters:

  • func function Function returning a boolean that will allow/deny a weapon to be fired.

Usage:

    -- Custom logic that is executed when a weapon is fired
local custom_fire_condition = function(player) {
    -- no weapons for dave
    if player:get_player_name() == "dave" then
        return false
    end

    return true
}

-- Our function will now be called when a player fires a weapon.
-- If the player's name is dave, their weapon will not fire.
boomstick_api.register_custom_fire_condition(custom_fire_condition)
boomstick_api.register_projectile_collision (func)
Registers a callback function to be called when any projectile has a collision. If you'd like certain behavior to happen when a projectile collides with something, you can pass another function as an argument to this function, and it will be executed when a projectile collides with something.

Parameters:

  • func function Function to be executed when a projectle has a collision.
boomstick_api.register_weapon_fire (func)
Registers a callback function to be called when any projectile has a collision. If you'd like certain behavior to happen when a projectile collides with something, you can pass another function as an argument to this function, and it will be executed when a projectile collides with something.

Parameters:

  • func function Function to be executed when a projectle has a collision.
boomstick_api.weapon_is_full (item_definition)
Returns a boolean for whether a weapon is at maximum capacity (i.e no more ammo will fit).

Parameters:

Returns:

    boolean - Indicating if the weapon is full.
boomstick_api.weapon_is_empty (item_definition)
Returns a boolean for whether or not a weapon is empty (i.e not loaded).

A convenience function that returns the rounds_loaded field from the weapon data.

Parameters:

Returns:

    boolean - Indicating if the weapon is empty.
boomstick_api.weapon_is_cocked (item_definition)
Returns a boolean for whether or not a weapon is ready to fire.

A convenience function that returns the cocked field from the weapon data. A weapon is considered cocked (and therefore ready to fire) when it is loaded and no cooldown timers are currently active on it.

Parameters:

Returns:

    boolean - Indicating if the weapon is ready to fire.
boomstick_api.fire_weapon (itemstack, user, pointed_thing)
Fires a weapon.

Parameters:

  • itemstack
    • An ItemStack passed by Minetest when called as a callback.
  • user
    • A player ObjectRef passed by Minetest when called as a callback. This is the player who fired the weapon.
  • pointed_thing
boomstick_api.fire_loaded_weapon (weapon_data, user, pointed_thing)
Fires a weapon as if it is loaded. Note: It is usually not necesary to call this function directly unless you are extending the mod or making custom behavior.

Parameters:

  • weapon_data
    • Weapon data for a weapon.
  • user
    • A player ObjectRef passed by Minetest when called as a callback. This is the player who fired the weapon.
  • pointed_thing
boomstick_api.spawn_smoke_particles (player, particles)
Generates smoke particles that look like smoke from a fired weapon Note: It is usually not necesary to call this function directly unless you are extending the mod or making custom behavior.

Parameters:

  • player
    • A player ObjectRef that the smoke particles will be created near. This would usually be the player firing the weapon.
  • particles
    • A table containing attributes of the particles.

Usage:

    boomstick_api.spawn_smoke_particles(player, {
    -- The number of smoke particles to spawn
    count = 5,

    -- The maximum possible size of each particle
    size = 2,

    -- The maximum possible variance in position, velocity, and acceleration
    between particles.
    variance = 0.25,

    -- How long each particle will linger before despawning
    lifespan = 2,

    -- The maximum possible velocity of a particle
    velocity = 2
})
boomstick_api.fire_empty_weapon (weapon_data, user)
Fires a weapon as if it is empty. Note: It is usually not necesary to call this function directly unless you are extending the mod or making custom behavior.

Parameters:

  • weapon_data
    • Weapon data for a weapon.
  • user
    • A player ObjectRef passed by Minetest when called as a callback. This is the player who fired the weapon.
boomstick_api.can_load_weapon (inventory_item, ammo_item)
Returns a boolean for whether or not a given weapon can be loaded.

Given one item (typically a weapon from an inventory), and a second item (typically an ammo stack from an inventory), return whether or not the weapon can be loaded. A weapon can be loaded if it is not empty, not full, and not under any active reload cooldown.

Note: This function nor the rest of the API handle the concept of a weapon item having a stack size of >1.

Parameters:

Returns:

    boolean - Incidating whether the weapon can be loaded.
boomstick_api.recoil (player, recoil)
Pushes the player's view up, simulating recoil.

Note: It is usually not necesary to call this function directly unless you are extending the mod or making custom behavior.

Parameters:

  • player
    • A player ObjectRef. This is the player who will experience recoil.
  • recoil number
boomstick_api.knockback (player, recoil)
Pushes the player backwards based on recoil.

Note: It is usually not necesary to call this function directly unless you are extending the mod or making custom behavior.

Parameters:

  • player
    • A player ObjectRef. This is the player who will experience recoil.
  • recoil number -
generated by LDoc 1.4.6