Add api documentation

This commit is contained in:
stujones11 2019-03-19 22:17:49 +00:00
parent 2a0b7808a1
commit cb922eaafd
2 changed files with 127 additions and 115 deletions

View file

@ -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`
},
}
```

View file

@ -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
},
}