projectile/api.txt

Tables
------

projectile.registered_projectiles
	A per-category list of lists, the categories being types of ranged weapons like "bow", "slingshot", etc.
	Within each category, key-value pairs are listed to link together the entity and item forms of ammo
	The item's name is the key, the entity's name is the value.

projectile.charge_levels
	A per-player list of lists that keeps track of data regarding ranged weapons that are currently being used.
	Whenever a weapon charge-up is cancelled, the charge_levels entry for that player will be cleared.
	When a weapon is being charged up, a table for that weapon's user is created containing the following:
	{
		slot = <index of wielded ranged weapon>,
		charge = <number>
	}



Regristration Functions
-----------------------

projectile.register_weapon(name, definition)
	--Register a new ranged weapon
	--Inherits from minetest.register_tool

	description = "Description",

	inventory_image = "image.png",
	inventory_image_2 = "image_charged.png",
	inventory_image_3 = "image_charged_full.png",
	--When creating a weapon that can be charged, you should provide different sprites when charging the weapon
	--and when the weapon is fully charged.

	durability = 100,
	--Defines how many times this weapon can be used before breaking.

	rw_category = "category",
	--A projectile weapon may only fire ammo types in the same category.
	--This mod provides "bow", "flintlock", and "slingshot"
	--You can use a custom category, as long as you also register custom ammo

	charge = false,
	--If true, right clicking will put the weapon in a charging state.
	--Once charging, right-click again to fire, or left-click to cancel.
	--If a weapon doesn't charge, right-clicking will always fire.
	--Defaults to false

	fire_while_charging = false,
	--If true, the weapon doesn't need to be fully charged to be fired.
	--A partially charged shot will still be weaker than a fully charged one, however.
	--Does nothing if charge is false
	--Defaults to false

	charge_time = 1,
	--The amount of time in seconds to finish charging.
	--Does nothing if charge is false
	--Defaults to false.

	damage = 1,
	--A damage multiplier applied to fired projectiles

	speed = 1,
	--A multiplier to the projectile's initial velocity

	can_fire = function(weapon, user)
	--Use this to create extra conditions for when a weapon can be fired.
	--Can't be used to negate the need for ammo.
	--Defaults to always return true.

	on_cancel = function(weapon, user)
	--This function is called whenever a charge is cut short, either by left-clicking, switching the selected hotbar index, or leaving the game.
	--Has no return value.

	on_fire = function(wep, user)
	--This function is called just before the projectile is created.
	--Has no return value.

	after_fire = function(weapon, user)
	--This function is called just after the projectile is created.
	--Has no return value.



projectile.register_projectile(name, usable_by, ammo, definition)
	--Register a new projectile entity and an associated ammo item.
	--Note that this function will NOT register a new item for you. Use one of minetest's normal item registration functions instead.
	--Inherits from minetest.register_entity.
	--usable_by: This should match the rw_category of the weapon that you want to use this ammo.
	--ammo: The name of the item that is consumed to create this projectile.

	image = "image.png",
	--A shortcut for initial_properties.texture. You can ignore this if you define a mesh for the projectile.

	damage = 5,
	--The base damage that this projectile deals.

	speed = 15,
	--The base initial velocity of this projectile, in meters/nodes per second.

	count = 1,
	--The amount of projectiles that is created per shot.
	--Meant for shotgun-like effects.
	--defaults to 1

	spread = 0,
	--The radius, in degrees, that projectiles can spread away from the player's look direction.
	--Defaults to 0

	collide_self = true,
	--As long as its true, a player can shoot their own projectiles.
	--If false, two projectiles owned by the same player will phase through each other.
	--Defaults to true.

	_on_step = function(self, dtime, moveresult)
	--Use this function to give your projectile an on_step callback.
	--If you try to use the regular on_step, it will be overwritten.

	on_impact = function(self, collisions)
	--This function is called when a node or object is struck.
	--Has no return value.
	--collisions is a table taken from on_step's moveresult, which contains the following:
	{
		type = string, -- "node" or "object",
                axis = string, -- "x", "y" or "z"
                node_pos = vector, -- if type is "node"
                object = ObjectRef, -- if type is "object"
                old_velocity = vector,
                new_velocity = vector,
	}



Misc Functions
--------------

projectile.shoot(wep, user, level)
	--Shoot out a projectile at the user's position.
	--Afterwards, deplete the ammo used and add wear to the weapon used.
	--level: The charge level at the time of firing.

function projectile.in_same_party(projectile, target)
	--If the parties mod is enabled, this checks if the projectile's owner is in the same party as the target.
	--Always returns false if the parties mod is not present.

projectile.autorotate_arrow(self)
	--Meant to be given to an arrow projectile's _on_step method, when that arrow uses a mesh.
	--This causes the arrow to spin as it travels.
	--Spin speed is dependent on velocity.

projectile.needs_gunpowder(wep, user)
	--Meant to be given to a flintlock's can_fire function.
	--Searches the user's main inventory for tnt:gunpowder.
	--If none is found, return false to prevent firing.
	--If some is found, consume it and return true.
	--If the player is already charging, skip this check and automatically return true. No need to take two gunpowder.

projectile.return_gunpowder(wep, user)
	--Meant to be used with a flintlock's on_cancel function.
	--projectile.needs_gunpowder takes gunpowder right before a charge is started.
	--This means that gunpowder needs to be added back to the inventory if the charge is cancelled.
	--If no space is left in the inventory for the gunpowder, drop it on the ground instead.