shooter/shooter/README.md

Minetest Mod - Shooter API [shooter]

Depends: default

Handles raycasting, blasting and audio-visual effects of dependent mods

Crafting

Gunpowder

1 x Coal Lump + 1 x Clay Lump = 5 x Gunpowder

output = "shooter:gunpowder 5",
type = "shapeless",
recipe = {"default:coal_lump", "default:clay_lump"},

Configuration

Override the following default settings by adding them to your minetest.conf file

Enable automatic weapons

Uses globalstep to detect left mouse button

shooter_automatic_weapons = true

Enable admin super weapons

Allows admins (server priv) to shoot all guns automatically Requires shooter_automatic_weapons to be true

shooter_admin_weapons = false

Enable node destruction with explosives

shooter_enable_blasting = true

Enable Crafting

shooter_enable_crafting = true

Enable hit particle effects

shooter_enable_particle_fx = true

Enable protection

Requires a protection mod that utilizes minetest.is_protected()

shooter_enable_protection = false

Particle texture

Particle texture used when a player or entity with the 'fleshy' armor group is hit

shooter_explosion = "shooter_hit.png"

Allow node destruction

shooter_allow_nodes = true

Node Drops

Drops the node item when hit, requires shooter_allow_nodes to be true Currently excludes 'blasting'

shooter_node_drops = false

Allow entity damage

Defaults to true in singleplayer mode

shooter_allow_entities = false

Allow player damage

Defaults to false in singleplayer mode

shooter_allow_players = true

Round update time

Maximum round 'step' processing interval, will inversely effect the long-range velocity of the virtual projectiles. This should always be greater than the dedicated server step time

shooter_rounds_update_time = 0.4

Entity damage coefficient

May be used to globaly increase or decrease damage done to entities/mobs

shooter_damage_multiplier = 1

API Documentation

Global tables

• shooter.registered_weapons: Registered weapons by itemstring
• shooter.config: Present configuration
• shooter.default_particles: Default hit particle definition

{
	amount = 15,
	time = 0.3,
	minpos = {x=-0.1, y=-0.1, z=-0.1},
	maxpos = {x=0.1, y=0.1, z=0.1},
	minvel = {x=-1, y=1, z=-1},
	maxvel = {x=1, y=2, z=1},
	minacc = {x=-2, y=-2, z=-2},
	maxacc = {x=2, y=-2, z=2},
	minexptime = 0.1,
	maxexptime = 0.75,
	minsize = 1,
	maxsize = 2,
	collisiondetection = false,
	texture = "shooter_hit.png",
}

Methods

• shooter.register_weapon(name, definition): Register a shooting weapon. -- See "Weapon Definition"
• shooter.get_weapon_spec(player, weaponname): Gets the spec for a particular weapon
  • Override this function to add support for per-player specs, for example
• shooter.get_configuration(config): Loads matching config settings into a table ref config
• shooter.spawn_particles(pos, particles): Adds particles at the specified position
  • particles is an optional table of overrides for shooter.default_particles
• shooter.play_node_sound(node, pos): Plays the registered 'dug' sound for the node at pos
• shooter.is_valid_object(object): Returns true if the object can be damaged
• shooter.punch_node(pos, spec): Punches the node at pos with the spec group capabilities
  • Returns true if the node was destroyed
• shooter.punch_object(object, tool_caps, dir, on_blast): Punches the object
  • Returns true if the object is damaged
  • object: Object to be punched, not checked for validity!
  • tool_caps: Tool capabilities of the weapon uesd -- See "Weapon Definition"
  • dir: Unit vector pointing from the source of the punch to the object, may be nil
  • on_blast: Respect entity on_blast damage callback
• shooter.fire_weapon(player, itemstack, spec): Adds a 'round' with spec to the processing que
• shooter.blast(pos, radius, fleshy, distance, user): Create explosion at pos
  • radius: Blast radius in nodes
  • fleshy: Damage to inflict on fleshy objects: (fleshy * 0.5 ^ distance) * 2
  • distance: Area of effect for objects
  • user: A player reference, used for protection
• shooter.get_shooting(name): Returns true if player name is holding the left mouse button or nil
  • Requires shooter_automatic_weapons to be set true
• shooter.set_shooting(name, is_shooting): Sets the left mouse button status of player name

Weapon Definition

Used by shooter.register_weapon

{
	description = "My Awesome Gun",
	inventory_image = "my_awesome_gun.png",
	reload_item = "itemstring",
		-- Reload Item, "shooter:ammo" is used if omitted
	unloaded_item = {
		-- Optional. Item to be registered as unloaded weapon item
		name = "itemstring",
		description = "My Awesome Gun (Unloaded)",
		inventory_image = "my_awesome_gun_unloaded.png",
	},
	on_use = function(itemstack, user, pointed_thing)
		-- Called before the built-in tool `one_use` handler
		-- Should return a valid `ItemStack` or `nil` to cancel the shot
		return itemstack
	end,
	on_hit = function(pointed_thing, spec, dir)
		-- May be used for arbitary shot effects like knock-back, etc.
		-- Return `true` to override built-in damage effects
		-- `pointed_thing`: Returned by `minetest.raycast()`
		-- `spec`: Gunspec of the weapon used including some additional fields
			-- `name`: Name of the weapon item, eg. `shooter_guns:rifle`
			-- `user`: Name of the player that fired the weapon
			-- `origin`: Initial starting position of the shot
		-- `dir`: Unit vector direction of the virtual shot
	end,
	spec = {
		-- Weapon specifications
		rounds = 100,
			-- Number of rounds, refilled by the defined reload item
		range = 200,
			-- Range (in nodes) of each shot
		step = 30,
			-- Distance per `shooter_rounds_update_time`
		shots = 1,
			-- Number of shots fired per `round`
		spread = 10,
			-- Spread of shots in degrees if `shots` > 1
			-- Uses a sunflower seed arrangement for even distributuion
		tool_caps = {
			-- Tool capabilities, used for object/player damage
			full_punch_interval = 1.0,
			damage_groups = {fleshy=3},
		},
		groups = {
			-- Damage groups, used to effect nodes as a normal tool item would
			snappy = 3,
			crumbly = 3,
			choppy = 3,
			fleshy = 2,
			oddly_breakable_by_hand = 2,
		},
		sounds = {
			-- Sound files (defaults)
			shot = "guns_rifle",
			reload = "shooter_reload",
			fail_shot = "shooter_click",
		},
		bullet_texture = "shooter_bullet.png",
			-- Particle texture file name for the projectile
		particles = {},
			-- Optional. Table of overrides for `shooter.default_particles`
	},
}