From bf41e116a1dbfd71be37a8e5f8aedc6686214884 Mon Sep 17 00:00:00 2001 From: Michieal Date: Sun, 3 Dec 2023 08:10:41 -0500 Subject: [PATCH] Fleshed out the API Documentation. Modified missing pieces of code. --- mods/PLAYER/mcl_fovapi/api.md | 78 ++++++++++++++++++++++++++++----- mods/PLAYER/mcl_fovapi/init.lua | 9 ++-- 2 files changed, 73 insertions(+), 14 deletions(-) diff --git a/mods/PLAYER/mcl_fovapi/api.md b/mods/PLAYER/mcl_fovapi/api.md index 05b8be29b..43a54de53 100644 --- a/mods/PLAYER/mcl_fovapi/api.md +++ b/mods/PLAYER/mcl_fovapi/api.md @@ -1,21 +1,79 @@ +### FOV API -registered_modifiers has defs of modifiers + + * [FOV API](#fov-api) + * [Description](#description) + * [Troubleshooting](#troubleshooting) + * [Modifier Definition](#modifier-definition-) + * [Global MCL_FOVAPI Tables](#global-mclfovapi-tables) + * [Namespaces](#namespaces) + * [Functions](#functions) + -applied_modifiers is indexed by player name +#### Description +This API defines and applies different Field Of View effects to players via MODIFIERS. -mcl_fovapi = {} +#### Troubleshooting +In the `init.lua` file for this module, there is a `DEBUG` variable at the top that will turn on logging. +Use it to see what is going on. -mcl_fovapi.default_fov = {} +#### Modifier Definition +```lua +def = { + modifer_name = name, + fov_factor = fov_factor, + time = time, + is_multiplier = is_multiplier, + exclusive = exclusive, + on_start = on_start, + on_end = on_end, +} +``` +* Modifier Name: The name of the Modifier, used to identify the specific modifier. Case sensitive. +* FOV Factor: A float value defining the FOV to apply. Can be an absolute or percentage, depending on Exclusive and + Is_Multiplier. +* Time: A float value defining the number of seconds to take when applying the FOV Factor. + Used to smoothly move between FOVs. Use 0 for an immediate FOV Shift. (Transition time.) +* Is Multiplier: A bool value used to specify if the FOV Factor is an absolute FOV value or if it should be a percentage + of the current FOV. Defaults to `true` if not defined. +* Exclusive: A bool value used to specify whether the modifier will override all other FOV modifiers. An example of this + is how the spy glass sets the FOV to be a specific value regardless of any other FOV effects applied. Defaults to + `false` if not defined. +* On Start: the `on_start` is a callback function `on_start(player)` that is called if defined. The parameter `player` + is a ref to the player that had the modifier applied. Called from `mcl_fovapi.apply_modifier` immediately after + the FOV Modifier has been applied. +* On End: the `on_end` is a callback function `on_end(player)` that is called if defined. The parameter `player` + is a ref to the player that had the modifier applied. Called from `mcl_fovapi.remove_modifier` immediately after + the FOV Modifier has been removed. -mcl_fovapi.registered_modifiers = {} +Note: passing incorrect values in the definition will have unintended consequences. -mcl_fovapi.applied_modifiers = {} +#### Global MCL_FOVAPI Tables +There are three tables that are accessible via the API. They are `registered_modifiers` and `applied_modifiers`. -function mcl_fovapi.register_modifier(name, fov_factor, time, is_multiplier, exclusive, on_start, on_end) +`mcl_fovapi.registered_modifiers` has the definitions of all the registered FOV Modifiers. Indexed by Modifier Name. +And, `mcl_fovapi.applied_modifiers` is indexed by the Player Name. It contains the names of all the modifiers applied to the +player. The `mcl_fovapi.default_fov` table is indexed by the Player Name, and contains the Default FOVs of the player from the +settings. (Expressed as a value usable in `player:set_fov`.) -function mcl_fovapi.apply_modifier(player, modifier_name) +#### Namespaces +`mcl_fovapi` is the default API Namespace. -function mcl_fovapi.remove_modifier(player, modifier_name) +#### Functions +`mcl_fovapi.register_modifier(name, fov_factor, time, is_multiplier, exclusive, on_start, on_end)` -function mcl_fovapi.remove_all_modifiers(player, time) +Used to register a new FOV Modifier for use. Must be called before applying said modifier to a player. +See Modifier Definition for what the parameters are. +`mcl_fovapi.apply_modifier(player, modifier_name)` + +Used to apply a registered FOV modifier to a player. Takes a reference to the player and the modifier's name (string). + +`mcl_fovapi.remove_modifier(player, modifier_name)` + +Used to remove a specific FOV modifier from a Player. Takes a reference to the player and the modifier's name (string). +Removed immediately. + +`mcl_fovapi.remove_all_modifiers(player)` + +Used to remove all FOV modifiers from a Player. Takes a reference to the Player. FOV change is instantaneous. diff --git a/mods/PLAYER/mcl_fovapi/init.lua b/mods/PLAYER/mcl_fovapi/init.lua index 649f582ab..ace5ca96f 100644 --- a/mods/PLAYER/mcl_fovapi/init.lua +++ b/mods/PLAYER/mcl_fovapi/init.lua @@ -27,23 +27,24 @@ minetest.register_on_joinplayer(function(player) end) --- clear when player leaves minetest.register_on_leaveplayer(function(player) local name = player:get_player_name() - -- Remove default FOV + + -- handle clean up mcl_fovapi.default_fov[name] = nil + mcl_fovapi.applied_modifiers[name] = nil end) function mcl_fovapi.register_modifier(name, fov_factor, time, is_multiplier, exclusive, on_start, on_end) if is_multiplier ~= true and is_multiplier ~= false then - is_multiplier = false + is_multiplier = true end if exclusive ~= true and exclusive ~= false then exclusive = false end local def = { modifer_name = name, - fov = fov_factor, + fov_factor = fov_factor, time = time, is_multiplier = is_multiplier, exclusive = exclusive,