mtcontrib/3d_armor
1
0
Fork 2
mirror of https://github.com/minetest-mods/3d_armor.git synced 2024-12-27 03:00:40 +01:00
Code Issues Releases Wiki Activity

Documentation and Screenshot Update (#26)

Browse Source 
* New screenshot
* Examples Added
* formatting
* Delete README.txt
* formatting
* Update README.md
This commit is contained in:
Sirrobzeroone 2020-12-03 18:38:41 +11:00 committed by GitHub
parent cbd1a1246b
commit 713b0c81d4
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
4 changed files with 476 additions and 212 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

476
3d_armor/README.md Normal file
View File

@ -0,0 +1,476 @@
# [mod] Visible Player Armor [3d_armor]
| | | | |
|--|--|--|--|
|-[Overview](#overview) |||-[API](#api)|
|-[Armor Configuration](#armor-configuration) |||- - [3d_Armor Item Storage](#3d_armor-item-storage)
|- - [disable_specific_materials](#to-disable-individual-armor-materials) |||- - [Armor Registration](#armor-registration)
|- - [armor_init_delay](#initialization-glitches-when-a-player-first-joins) |||- - [Registering Armor Groups](#registering-armor-groups)
|- - [armor_init_times](#number-of-initialization-attempts) |||- - [Groups used by 3d_Armor](#groups-used-by-3d_armor)
|- - [armor_bones_delay](#armor-not-in-bones-due-to-server-lag) |||- - - [Elements](#elements)
|- - [armor_update_time](#how-often-player-armor-items-are-updated) |||- - - [Attributes](#attributes)
|- - [armor_drop](#drop-armor-when-a-player-dies) |||- - - [Physics](#physics)
|- - [armor_destroy](#destroy-armor-when-a-player-dies) |||- - - [Durability](#durability)
|- - [armor_level_multiplier](#armor-level-multiplyer) |||- - [Armour Functions](#armour-functions)
|- - [armor_heal_multiplier](#armor-healing-multiplyer) |||- - - [armor:set_player_armor](#armor-set_player_armor)
|- - [armor_water_protect](#enable-water-protection) |||- - - [armor:punch](#armor-punch)
|- - [armor_fire_protect](#enable-fire-protection) |||- - - [armor:damage](#armor-damage)
|- - [armor_punch_damage](#enable-punch-damage-effects) |||- - - [armor:remove_all](#armor-remove_all)
|- - [armor_migrate_old_inventory](#migration-of-old-armor-inventories) |||- - - [armor:equip](#armor-equip)
|- - [wieldview_update_time](#how-often-player-wield-items-are-updated) |||- - - [armor:unequip](#armor-unequip)
| - [Credits](#credits) |||- - - [armor:update_skin](#armor-update_skin)
| |||- - [Callbacks](#Callbacks)
| |||- - - [Item callbacks](#item-callbacks)
| |||- - - [Global callbacks](#global-callbacks)
# Overview
**Depends:** default
**Recommends:** sfinv, unified_inventory or smart_inventory (use only one to avoid conflicts)
**Supports:** player_monoids and armor_monoid
Adds craftable armor that is visible to other players. Each armor item worn contributes to
a player's armor group level making them less vulnerable to weapons.
Armor takes damage when a player is hurt but also offers a percentage chance of healing.
Overall level is boosted by 10% when wearing a full matching set.
# Armor Configuration
Override the following default settings by adding them to your ***minetest.conf*** file.
### To disable individual armor materials
**set the below to false**
armor_material_wood = true
armor_material_cactus = true
armor_material_steel = true
armor_material_bronze = true
armor_material_diamond = true
armor_material_gold = true
armor_material_mithril = true
armor_material_crystal = true
### Initialization glitches when a player first joins
**Increase to prevent glitches**
armor_init_delay = 2
### Number of initialization attempts
**Increase to prevent glitches - Use in conjunction with armor_init_delay if initialization problems persist.**
armor_init_times = 10
### Armor not in bones due to server lag
**Increase to help resolve**
armor_bones_delay = 1
### How often player armor items are updated
**Number represents how often per second update is performed, higher value means less performance hit for servers but armor items maybe delayed in updating when switching.Fractional seconds also supported eg 0.1**
armor_update_time = 1
### Drop armor when a player dies
**Uses bones mod if present, otherwise items are dropped around the player when false.**
armor_drop = true
### Destroy armor when a player dies
**overrides armor_drop.**
armor_destroy = false
### Armor level multiplyer
**Increase to make armor more effective and decrease to make armor less effective**
**eg: level_multiplier = 0.5 will reduce armor level by half.**
armor_level_multiplier = 1
### Armor healing multiplyer
**Increase to make armor healing more effective and decrease to make healing less effective**
**eg: armor_heal_multiplier = 0 will disable healing altogether.**
armor_heal_multiplier = 1
### Enable water protection
**periodically restores breath when activated**
armor_water_protect = true
### Enable fire protection
**defaults to true if using ethereal mod**
armor_fire_protect = false
### Enable punch damage effects.
armor_punch_damage = true
### Migration of old armor inventories
armor_migrate_old_inventory = true
### How often player wield items are updated
**Number represents how often per second update is performed, higher value means less performance hit for servers but wield items maybe delayed in updating when switching. Fractional seconds also supported eg 0.1**
***Note this is MT engine functionality but included for completness***
wieldview_update_time = 1
# API
## 3d_Armor item storage
3d_Armor stores each armor piece a player currently has equiped in a ***detached*** inventory. The easiest way to access this inventory if needed is using this line of code
local _, armor_inv = armor:get_valid_player(player, "3d_armor")
**Example**
armor:register_on_equip(function(player, index, stack)
local _, armor_inv = armor:get_valid_player(player, "3d_armor")
for i = 1, 6 do
local stack = armor_inv:get_stack("armor", i)
if stack:get_name() == "3d_armor:chestplate_gold" then
minetest.chat_send_player(player:get_player_name(),"Got to love the Bling!!!")
end
end
end)
## Armor Registration
armor:register_armor(name, def)
Wrapper function for `minetest.register_tool`, which enables the easy registration of new armor items. While registering armor as a tool item is still supported, this may be deprecated in future so all armor items should be registered using *armor:register_armor(name,def)*.
### Additional fields supported by 3d_armor
texture = <filename>
preview = <filename>
armor_groups = <table>
damage_groups = <table>
reciprocate_damage = <bool>
on_equip = <function>
on_unequip = <function>
on_destroy = <function>
on_damage = <function>
on_punched = <function>
***Reciprocal tool*** damage will apply damage back onto the attacking tool/weapon, however this will only be done by the first armor inventory item with `reciprocate_damage = true`, damage does not stack.
**Example Simple:**
armor:register_armor("mod_name:chestplate_leather", {
description = "Leather Chestplate",
inventory_image = "mod_name_inv_chestplate_leather.png",
texture = "mod_name_leather_chestplate.png",
preview = "mod_name_leather_chestplate_preview.png",
groups = {armor_torso=1, armor_heal=0, armor_use=2000, flammable=1},
armor_groups = {fleshy=10},
damage_groups = {cracky=3, snappy=2, choppy=3, crumbly=2, level=1}
})
*See ***armor.lua*** under **3d_armor>>3d_armor** for further examples*
**Extended functionality**
The values for ***texture*** and ***preview*** do not need to be included when registering armor if they follow the naming convention in the textures mod folder of:
***texture:*** *mod_name_leather_chestplate.png*
***preview:*** *mod_name_leather_chestplate_preview.png*
## Registering Armor Groups
3d armor has a built in armor group which is ***fleshy*** all players base vulnerability to being fleshy is ***100***.
3d armour allows for the easy registration/addition of new armor groups::
armor:register_armor_group(group, base)
***group:*** Is the name of the new armor group
***base*** Is the starting vulnerability that all players have to that new group. This dosent need to be 100.
**Example**
armor:register_armor_group("radiation", 100)
New armor group is registered called *radiation* and all players start off with a base vulnerability of *100* to radiation.
**Example** *Showing armor reg, new group usage and custom function*
armor:register_armor("mod_name:speed_boots", {
description = "Speed Boots",
inventory_image = "mod_name_speed_boots_inv.png",
texture = "mod_name_speed_boots.png",
preview = "mod_name_speed_boots_preview.png",
groups = {armor_feet=1, armor_use=500, physics_speed=1.2, flammable=1},
armor_groups = {fleshy=10, radiation=10},
damage_groups = {cracky=3, snappy=3, choppy=3, crumbly=3, level=1},
reciprocate_damage = true,
on_destroy = function(player, index, stack)
local pos = player:get_pos()
if pos then
minetest.sound_play({
name = "mod_name_break_sound",
pos = pos,
gain = 0.5,
})
end
end,
})
### Tools/weapons and new armor groups
The above allows armor to block/prevent new damage types but you also need to assign the new damage group to a tool/weapon or even a node (see technic mod) to make wearing the armor item meaningful. Simply add the ***armor_groups*** name to the tool items ***damage_groups***.
**Example**
minetest.register_tool("mod_name:glowing_sword", {
description = "Glowing Sword",
inventory_image = "mod_name_tool_glowingsword.png",
tool_capabilities = {full_punch_interval = 1.2,max_drop_level=0,
groupcaps={
cracky = {times={[3]=1.60}, uses=10, maxlevel=1},},
damage_groups = {fleshy=10,radiation=20},
},
sound = {breaks = "default_tool_breaks"},
groups = {pickaxe = 1, flammable = 2}
})
## Groups used by 3d_Armor
3d_armor has many default groups already registered, these are categorized under 4 main headings
- **Elements:** armor_head, armor_torso, armor_legs, armor_feet
- **Attributes:** armor_heal, armor_fire, armor_water
- **Physics:** physics_jump, physics_speed, physics_gravity
- **Durability:** armor_use, flammable
***Note: for calculation purposes "Attributes" and "Physics" values stack***
### Elements
Additional armor elements can be added by dependant mods, for example shields adds the group armor_shield which has by default a limit that only 1 shield can be worn at a time.
Adding Elements is more complex but the below code can be used to add new elements;
if minetest.global_exists("armor") and armor.elements then
table.insert(armor.elements, "hands")
local mult = armor.config.level_multiplier or 1
armor.config.level_multiplier = mult * 0.5
end
**1st line** not strictly needed but checks that the global table "armor" and subtable "elements" exists
**2nd line** adds a new value to the armor.elements table called "hands"
**3rd line** in this case will be set to one ***note: need more detail here***
**4th line** simply sets the multiplier, by setting 0.5 smaller armor becomes less effective and larger more effective. good values are between 0.1 and 1 in increments of 0.1.
See ***init.lua*** under **3d_armor>>shields** for a further example
The new armor item can now be registered using the new element
**Example**
armor:register_armor("mod_name:gloves_wood", {
description = "Wood Gauntlets",
inventory_image = "mod_name_inv_gloves_wood.png",
texture = "mod_name_gloves_wood.png",
preview = "mod_name_gloves_wood_preview.png",
groups = {armor_hands=1, armor_heal=0, armor_use=2000, flammable=1},
armor_groups = {fleshy=5},
damage_groups = {cracky=3, snappy=2, choppy=3, crumbly=2, level=1},
})
### Attributes
Three attributes are avaliable in 3d_armor these are armor_heal, armor_fire and armor_water. Although possible to add additional attributes they would do nothing as code needs to be provide to specifiy the behaviour this could be done in a dependant mod
#### Armor_heal
This isn't how much the armor will heal but relates to the chance the armor will completely block the damage. For each point of ***armor_heal*** there is a 1% chance that damage will be completely blocked, this value will stack between all armor pieces
**Example**
The below Diamond chestplate has a 12% chance to completely block all damage (armor_heal=12), however so do boots, helmet and trousers so if the player was wearing all 4 pieces they would have a 48% chance of blocking all damage each attack.
armor:register_armor("3d_armor:chestplate_diamond", {
description = S("Diamond Chestplate"),
inventory_image = "3d_armor_inv_chestplate_diamond.png",
groups = {armor_torso=1, armor_heal=12, armor_use=200},
armor_groups = {fleshy=20},
damage_groups = {cracky=2, snappy=1, choppy=1, level=3},
})
#### Armor_fire
***"Armor_fire"*** provides 5 levels of fire protection
- level 1 protects against torches
- level 2 protects against crystal spike (Ethereal mod)
- level 3 protects against fire
- level 4 unused
- level 5 protects against lava
**Example**
armor:register_armor("mod_name:fire_proof_jacket", {
description = "Fire Proof Jacket",
inventory_image = "mod_name_inv_fire_proof_jacket.png",
groups = {armor_torso=1, armor_fire=3, armor_use=1000},
armor_groups = {fleshy=10},
damage_groups = {cracky=2, snappy=1, choppy=1, level=3},
})
#### Armor_water
***"Armor_water"*** will periodically restore a players breath when underwater. This only has one level or state, which is armor_water=1
**Example**
armor:register_armor("mod_name:helmet_underwater_breath", {
description = "Helmet of Underwater Breathing",
inventory_image = "mod_name_inv_helmet_underwater_breath.png",
groups = {armor_head=1, armor_water=1, armor_use=1000},
armor_groups = {fleshy=5},
damage_groups = {cracky=2, snappy=1, choppy=1, level=3},
})
### Physics
The physics attributes supported by 3d_armor are ***physics_jump, physics_speed and physics_gravity***. Although 3d_armor supports the use of this with no other mods it is recommended that the mod [player_monoids](https://forum.minetest.net/viewtopic.php?t=14895) is used to help with intermod compatability.
***physics_jump*** - Will increase/decrease the jump strength of the player so they can jump more/less. Done as a fractional so "physics_jump=1.5" will increase jump strength by 50%.
***physics_speed*** - Will increase/decrease the walk speed of the player so they walk faster/slower. Done as a fractional so "physics_speed=1.5" will increase speed by 50%.
***physics_gravity*** - Will increase/decrease gravity the player experiences so it's higher/lower. Done as a fractional so "physics_gravity=1.5" will increase gravity by 50%.
*Note: The player physics modifications won't be applied via `set_physics_override` if `player_physics_locked` is set to 1 in the respective player's meta.*
### Durability
Durability is determined by the value assigned to the group ***armor_use***. The higher the ***armor_use*** value the faster/more quickly it is damaged/degrades. This is calculated using the formula:
Total uses = approx(65535/armor_use)
**Example**
All wood armor items have an ***armor_use=2000***;
65535/2000 = 32.76 (32)
After 32 uses(hits) the armor item will break.
All diamond armor items have an ***armor_use=200***;
65535/2000 = 327.6 (327)
After 327 uses(hits) the armor item will break.
## Armor Functions
### armor set_player_armor
armor:set_player_armor(player)
Primarily an internal function but can be called externally to apply any
changes that might not otherwise get handled.
### armor punch
armor:punch(player, hitter, time_from_last_punch, tool_capabilities)
Used to apply damage to all equipped armor based on the damage groups of
each individual item.`hitter`, `time_from_last_punch` and `tool_capabilities`
are optional but should be valid if included.
### armor damage
armor:damage(player, index, stack, use)
Adds wear to a single armor itemstack, triggers `on_damage` callbacks and
updates the necessary inventories. Also handles item destruction callbacks
and so should NOT be called from `on_unequip` to avoid an infinite loop.
### armor remove_all
armor:remove_all(player)
Removes all armors from the player's inventory without triggering any callback.
### armor equip
armor:equip(player, armor_name)
Equip the armor, removing the itemstack from the main inventory if there's one.
### armor unequip
armor:unequip(player, armor_name)
Unequip the armor, adding the itemstack to the main inventory.
### armor update_skin
armor:update_skin(player_name)
Triggers a skin update with the same action as if a field with `skins_set` was submitted.
## Callbacks
### Item Callbacks
In all of the below when armor is destroyed `stack` will contain a copy of the previous stack.
*unsure what this note means may apply to all item callbacks or just on_punched*
Return `false` to override armor damage effects.
#### on_equip
on_equip = func(player, index, stack)
#### on_unequip
on_unequip = func(player, index, stack)
#### on_destroy
on_destroy = func(player, index, stack)
#### on_damage
on_damage = func(player, index, stack)
#### on_punched
on_punched = func(player, hitter, time_from_last_punch, tool_capabilities)
`on_punched` is called every time a player is punched or takes damage, `hitter`, `time_from_last_punch` and `tool_capabilities` can be `nil` and will be in the case of fall damage.
When fire protection is enabled, hitter == "fire" in the event of fire damage.
### Global Callbacks
#### armor register_on_update
armor:register_on_update(function(player))
#### armor register_on_equip
armor:register_on_equip(function(player, index, stack))
#### armor register_on_unequip
armor:register_on_unequip(function(player, index, stack))
#### armor register_on_destroy
armor:register_on_destroy(function(player, index, stack))
**Example**
armor:register_on_update(function(player)
print(player:get_player_name().." armor updated!")
end)
# Credits
### The below have added too, tested or in other ways contributed to the development and ongoing support of 3d_Armor
|Stu |Stujones11 |Stu |Github Ghosts |
|:---------------:|:---------------:|:---------------:|:---------------:|
|Pavel_S |BlockMen |Tenplus1 |donat-b |
|JPRuehmann |BrandonReese |Megaf |Zeg9 |
|poet.nohit |Echoes91 |Adimgar |Khonkhortisan |
|VanessaE |CraigyDavi |proller |Thomasrudin |
|Byakuren |kilbith (jp) |afflatus |G1ov4 |
|Thomas-S |Dragonop |Napiophelios |Emojigit |
|rubenwardy |daviddoesminetest|bell07 |OgelGames |
|tobyplowy |crazyginger72 |fireglow |bhree |
|Lone_Wolf(HT) |Wuzzy(2) |numberZero |Monte48 |
|AntumDeluge |Terumoc |runsy |Dacmot |
|codexp |davidthecreator |SmallJoker |orbea |
|BuckarooBanzay |daret |Exeterdad |Calinou |
|Pilcrow182 |indriApollo |HybridDog |CraigyDavi |
|Paly-2 |Diogogomes | | |
*Note: Names gathered from 3d_armor forum thread and github, I may have missed some people, apologises if I have - S01*

212
3d_armor/README.txt
View File

@ -1,212 +0,0 @@
[mod] Visible Player Armor [3d_armor]
=====================================
Depends: default
Recommends: sfinv, unified_inventory or smart_inventory (use only one to avoid conflicts)
Supports: player_monoids and armor_monoid
Adds craftable armor that is visible to other players. Each armor item worn contributes to
a player's armor group level making them less vulnerable to weapons.
Armor takes damage when a player is hurt but also offers a percentage chance of healing.
Overall level is boosted by 10% when wearing a full matching set.
Fire protection added by TenPlus1 when using crystal armor if Ethereal mod active, level 1
protects against torches, level 2 for crystal spike, level 3 for fire, level 5 for lava.
Armor Configuration
-------------------
Override the following default settings by adding them to your minetest.conf file.
-- Set false to disable individual armor materials.
armor_material_wood = true
armor_material_cactus = true
armor_material_steel = true
armor_material_bronze = true
armor_material_diamond = true
armor_material_gold = true
armor_material_mithril = true
armor_material_crystal = true
-- Increase this if you get initialization glitches when a player first joins.
armor_init_delay = 2
-- Number of initialization attempts.
-- Use in conjunction with armor_init_delay if initialization problems persist.
armor_init_times = 10
-- Increase this if armor is not getting into bones due to server lag.
armor_bones_delay = 1
-- How often player armor items are updated.
armor_update_time = 1
-- Drop armor when a player dies.
-- Uses bones mod if present, otherwise items are dropped around the player.
armor_drop = true
-- Pulverise armor when a player dies, overrides armor_drop.
armor_destroy = false
-- You can use this to increase or decrease overall armor effectiveness,
-- eg: level_multiplier = 0.5 will reduce armor level by half.
armor_level_multiplier = 1
-- You can use this to increase or decrease overall armor healing,
-- eg: armor_heal_multiplier = 0 will disable healing altogether.
armor_heal_multiplier = 1
-- Enable water protection (periodically restores breath when activated)
armor_water_protect = true
-- Enable fire protection (defaults true if using ethereal mod)
armor_fire_protect = false
-- Enable punch damage effects.
armor_punch_damage = true
-- Enable migration of old armor inventories
armor_migrate_old_inventory = true
API
---
Armor Registration:
armor:register_armor(name, def)
Wrapper function for `minetest.register_tool`, while registering armor as
a tool item is still supported, this may be deprecated in future so new code
should use this method.
Additional fields supported by 3d_armor:
texture = <filename>
preview = <filename>
armor_groups = <table>
damage_groups = <table>
reciprocate_damage = <bool>
on_equip = <function>
on_unequip = <function>
on_destroy = <function>
on_damage = <function>
on_punched = <function>
armor:register_armor_group(group, base)
Example:
armor:register_armor_group("radiation", 100)
armor:register_armor("mod_name:speed_boots", {
description = "Speed Boots",
inventory_image = "mod_name_speed_boots_inv.png",
texture = "mod_name_speed_boots.png",
preview = "mod_name_speed_boots_preview.png",
groups = {armor_feet=1, armor_use=500, physics_speed=1.2, flammable=1},
armor_groups = {fleshy=10, radiation=10},
damage_groups = {cracky=3, snappy=3, choppy=3, crumbly=3, level=1},
reciprocate_damage = true,
on_destroy = function(player, index, stack)
local pos = player:get_pos()
if pos then
minetest.sound_play({
name = "mod_name_break_sound",
pos = pos,
gain = 0.5,
})
end
end,
})
See armor.lua, technic_armor and shields mods for more examples.
Default groups:
Elements: armor_head, armor_torso, armor_legs, armor_feet
Attributes: armor_heal, armor_fire, armor_water
Physics: physics_jump, physics_speed, physics_gravity
Durability: armor_use, flammable
Notes:
Elements may be modified by dependent mods, eg shields adds armor_shield.
Attributes and physics values are 'stackable', durability is determined
by the level of armor_use, total uses == approx (65535/armor_use), non-fleshy
damage groups need to be defined in the tool/weapon used against the player.
Reciprocal tool damage will be done only by the first armor inventory item
with `reciprocate_damage = true`
Armor Functions:
armor:set_player_armor(player)
Primarily an internal function but can be called externally to apply any
changes that might not otherwise get handled.
armor:punch(player, hitter, time_from_last_punch, tool_capabilities)
Used to apply damage to all equipped armor based on the damage groups of
each individual item.`hitter`, `time_from_last_punch` and `tool_capabilities`
are optional but should be valid if included.
armor:damage(player, index, stack, use)
Adds wear to a single armor itemstack, triggers `on_damage` callbacks and
updates the necessary inventories. Also handles item destruction callbacks
and so should NOT be called from `on_unequip` to avoid an infinite loop.
armor:remove_all(player)
Removes all armors from the player's inventory without triggering any callback.
armor:equip(player, armor_name)
Equip the armor, removing the itemstack from the main inventory if there's one.
armor:unequip(player, armor_name)
Unequip the armor, adding the itemstack to the main inventory.
armor:update_skin(player_name)
Triggers a skin update with the same action as if a field with `skins_set` was submitted.
Item Callbacks:
on_equip = func(player, index, stack)
on_unequip = func(player, index, stack)
on_destroy = func(player, index, stack)
on_damage = func(player, index, stack)
on_punched = func(player, hitter, time_from_last_punch, tool_capabilities)
Notes:
`on_punched` is called every time a player is punched or takes damage, `hitter`,
`time_from_last_punch` and `tool_capabilities` can be `nil` and will be in the
case of fall damage, etc. When fire protection is enabled, hitter == "fire"
in the event of fire damage. Return `false` to override armor damage effects.
When armor is destroyed `stack` will contain a copy of the previous stack.
Global Callbacks:
armor:register_on_update(func(player))
armor:register_on_equip(func(player, index, stack))
armor:register_on_unequip(func(player, index, stack))
armor:register_on_destroy(func(player, index, stack))
Global Callback Example:
armor:register_on_update(function(player)
print(player:get_player_name().." armor updated!")
end)
Note:
The player physics modifications won't be applied via `set_physics_override` if `player_physics_locked` is set to 1
in the respective player's meta.

BIN
screenshot.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 65 KiB

After

Width:  |  Height:  |  Size: 117 KiB

BIN
screenshot.xcf Normal file
View File

Binary file not shown.