From cb922eaafd083d2c0267c26f4eeec5259048e14b Mon Sep 17 00:00:00 2001 From: stujones11 Date: Tue, 19 Mar 2019 22:17:49 +0000 Subject: [PATCH] Add api documentation --- shooter/README.md | 152 +++++++++++++++++++++++++++++++++++++-------- shooter/doc/api.md | 90 --------------------------- 2 files changed, 127 insertions(+), 115 deletions(-) delete mode 100644 shooter/doc/api.md diff --git a/shooter/README.md b/shooter/README.md index da7e723..28eb383 100644 --- a/shooter/README.md +++ b/shooter/README.md @@ -3,68 +3,170 @@ Minetest Mod - Shooter API [shooter] Depends: default -Handles raycasting, blasting and audio-visual effects of dependent mods. +Handles raycasting, blasting and audio-visual effects of dependent mods Configuration ------------- -Override the following default settings by adding them to your minetest.conf file. +Override the following default settings by adding them to your minetest.conf file --- Enable automatic weapons, uses globalstep to detect left mouse button +### Enable automatic weapons -`shooter_admin_weapons = true` +Uses globalstep to detect left mouse button --- Enable admin super weapons --- This lets admins shoot guns automatically after 2 seconds without munition. +`shooter_automatic_weapons = true` + +### Enable admin super weapons + +Allows admins (server priv) shoot all guns automatically `shooter_admin_weapons = false` --- Enable node destruction with explosives -shooter_enable_blasting = true +### Enable node destruction with explosives --- Enable Crafting +`shooter_enable_blasting = true` + +### Enable Crafting `shooter_enable_crafting = true` --- Enable particle effects +### Enable hit particle effects `shooter_enable_particle_fx = true` --- Enable protection mod support, requires a protection mod that utilizes --- minetest.is_protected(), tested with TenPlus1's version of [protector] +### Enable protection + +Requires a protection mod that utilizes `minetest.is_protected()` `shooter_enable_protection = false` --- Particle texture used when a player or entity is hit +### 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 +### Allow node destruction `shooter_allow_nodes = true` --- Allow entities in multiplayer mode +### Allow entities + +Defaults to `true` in singleplayer mode `shooter_allow_entities = false` --- Allow players in multiplayer mode +### Allow players + +Defaults to `false` in singleplayer mode `shooter_allow_players = true` --- How often objects are fully reloaded +### Round update time -`shooter_object_reload_time = 1` - --- How often object positions are updated - -`shooter_object_update_time = 0.25` - --- How often rounds are processed +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` +### Camera Height + +Player eye offset used for rayasting and particle effects + +`shooter_camera_height = 1.5` + API Documentation ----------------- -TODO +### Global tables +* `shooter.registered_weapons`: Registered weapons by itemstring +* `shooter.config`: Present configuration +* `shooter.default_particles`: Default hit particle definition +```Lua +{ + 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.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.punch_node(pos, spec)`: Punches the node at `pos` with the `spec` group capabilities +* `shooter.is_valid_object(object)`: Returns `true` if the object can be damaged +* `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 and object damage +* `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` + +```Lua +{ + 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_hit = function(pointed_thing, spec, dir) + -- May be used for arbitary shot effects like knock-back, etc. + end, + spec = { + -- Weapon specifications + rounds = 100, + -- Number of rounds, refilled by the defined reload item + range = 200, + -- Range (in nodes) of each shot + 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` + }, +} +``` diff --git a/shooter/doc/api.md b/shooter/doc/api.md deleted file mode 100644 index 79e6fff..0000000 --- a/shooter/doc/api.md +++ /dev/null @@ -1,90 +0,0 @@ -Shooter API Reference Alpha (DEV) -================================= - -IMPORTANT: This WIP & unfinished file contains the definitions of current advanced_npc functions -(Some documentation is lacking, so please bear in mind that this WIP file is just to enhance it) - - -Summary -------- -* Introduction -* Register a Weapon -* Definition tables - - -Introduction ------------- -An experimental first person shooter mod that uses simple vector mathematics -to produce an accurate and server-firendly method of hit detection. - -By default this mod is configured to work only against other players in -multiplayer mode and against Simple Mobs [mobs] in singleplayer mode. - -Default configuration can be customised by adding a shooter.conf file to -the mod's main directory, see shooter.conf.example for more details. - -This is still very much a work in progress which I eventually plan to use -as the base for a 'Spades' style FPS game using the minetest engine. - -Register a Weapon ------------------ -The API works with tools and items that represent a weapon, -then you should register the weapon and another support items (like ammo). - -### Methods -* `shooter:register_weapon(weapon_name, {Weapon Definitions})`: Register a weapon item - `weapon_name` is the itemstring for a tool to be registered - -Global Tables -------------- -* `shooter.registered_weapons`: Registered weapons by itemstring - -Definition tables ------------------ - -### Weapon Definitions (`shooter:register_weapon`) - - { - description = "Rifle", -- Weapon description name - - inventory_image = "guns_rifle.png", -- Inventory imagem for the weapon item - - rounds = 100, --[[ Amount of shots - ^ Refilled only by the defined reload item ]] - - reload_item = "itemstring", --[[ Reload Item - ^ If omitted, "shooter:ammo" is used ]] - - unloaded_item = { -- OPTIONAL | Item to be registered for unloaded weapon item - name = "itemstring", -- Itemstring to be registered - description = "Rifle (Unloaded)", -- Weapon description name - inventory_image = "guns_rifle_unloaded.png", -- Inventory imagem for the unloaded weapon item - not_in_creative_inventory = true, -- OPTIONAL | If true, does not display unloaded item in creative inventory - }, - - spec = { -- Weapon Aspects - - range = 200, -- Range (in blocks) of shot - - tool_caps = { -- Tool capabilities for registered item tool - full_punch_interval = 1.0, - damage_groups={fleshy=3} - }, - - groups = { -- Projectile destruction force - snappy=3, - crumbly=3, - choppy=3, - fleshy=2, - oddly_breakable_by_hand=2 - }, - - sounds = { -- Sound files - shot = "guns_rifle", -- When weapon shoots (if omitted, "guns_rifle" is used) - reload = "shooter_reload", -- When reload weapon (if omitted, "shooter_reload" is used) - fail_shot = "shooter_click", -- When the weapon fail by unloaded (if omitted, "shooter_click" is used) - }, - - particle = "shooter_bullet.png", -- Particle texture file name for projectile - }, - }