From 8075156b6228dbe05de98d3b82f59a8f47dae275 Mon Sep 17 00:00:00 2001 From: Wuzzy Date: Sun, 9 Jun 2024 23:12:42 +0200 Subject: [PATCH] Add player_api compability layer --- DEVELOPERS.md | 5 ++- mods/player_api/API.md | 91 +++++++++++++++++++++++++++++++++++++++ mods/player_api/README.md | 19 ++++++++ mods/player_api/init.lua | 13 ++++++ mods/player_api/mod.conf | 3 ++ 5 files changed, 130 insertions(+), 1 deletion(-) create mode 100644 mods/player_api/API.md create mode 100644 mods/player_api/README.md create mode 100644 mods/player_api/init.lua create mode 100644 mods/player_api/mod.conf diff --git a/DEVELOPERS.md b/DEVELOPERS.md index 4ad1a270..8e80995d 100644 --- a/DEVELOPERS.md +++ b/DEVELOPERS.md @@ -52,6 +52,7 @@ file named `API.md`. Mods with documented APIs: +* `player_api`: Player model handling, model animation, textures (see also `rp_player`) * `rp_armor`: Armor information and registration * `rp_achievements`: Add and trigger achievements * `rp_bed`: Get, set and unset (re)spawn position; query bed info @@ -77,7 +78,9 @@ Mods with documented APIs: * `rp_paint`: Add paintable nodes; set/remove paint of node * `rp_partialblocks`: Register partial blocks (slabs, stairs) * `rp_pathfinder`: Advanced pathfinding -* `rp_player`: Player model handling, model animation, textures +* `rp_player`: Same as `player_api`, but with extra features specific to Repixture. Only use this if + you need those extra features or for internal Repixture development. + Otherwise, use `player_api`. * `rp_player_effects`: Add player effects (required if you want to modify player physics) * `rp_sounds`: Node sounds * `rp_spyglass`: Spyglass diff --git a/mods/player_api/API.md b/mods/player_api/API.md new file mode 100644 index 00000000..0b296733 --- /dev/null +++ b/mods/player_api/API.md @@ -0,0 +1,91 @@ +# `player_api` Compability Layer API + +The player API can register player models and update the player's appearance. + +## Should I use this mod? + +If you want to handle player stuff from external mods, the answer is usually yes. +If you need some advanced Repixture-specific features, you may depend +on `rp_player` instead. + +This mod is the Repixture implementation of `player_api` originally from Minetest Game. +It is API-compatible with Minetest Game's `player_api` from Minetest Game 5.8.0. +Technically, it is just a wrapper around `rp_player`, provided for compability. + +## Function reference + +The following functions are available: + +* `player_api.globalstep(dtime, ...)` + * The function called by the globalstep that controls player animations. + You can override this to replace the globalstep with your own implementation. + * Receives all args that `minetest.register_globalstep()` passes + +* `player_api.register_model(name, def)` + * Register a new model to be used by players + * `name`: model filename such as "character.x", "foo.b3d", etc. + * `def`: see [#Model definition] + * Saved to `player_api.registered_models` + +* `player_api.registered_models[name]` + * Get a model's definition + * `name`: model filename + * See [#Model definition] + +* `player_api.set_model(player, model_name)` + * Change a player's model + * `player`: PlayerRef + * `model_name`: model registered with `player_api.register_model` + +* `player_api.set_animation(player, anim_name, speed)` + * Applies an animation to a player if speed or `anim_name` differ from the currently playing animation + * `player`: PlayerRef + * `anim_name`: name of the animation + * `speed`: keyframes per second. If nil, the default from the model def is used + +* `player_api.set_textures(player, textures)` + * Sets player textures + * `player`: PlayerRef + * `textures`: array of textures. If nil, the default from the model def is used + +* `player_api.set_textures(player, index, texture)` + * Sets one of the player textures + * `player`: PlayerRef + * `index`: Index into array of all textures + * `texture`: the texture string + +* `player_api.get_animation(player)` + * Returns a table containing fields `model`, `textures` and `animation` + * Any of the fields of the returned table may be nil + * `player`: PlayerRef + +* `player_api.player_attached` + * A table that maps a player name to a boolean + * If the value for a given player is set to true, the default player animations + (walking, digging, ...) will no longer be updated, and knockback from damage is + prevented for that player + * Example of usage: A mod sets a player's value to true when attached to a vehicle + +## Model definition + + { + animation_speed = 30, -- Default animation speed, in keyframes per second + textures = {"character.png"}, -- Default array of textures + animations = { + -- [anim_name] = { + -- x = , + -- y = , + -- collisionbox = , -- (optional) + -- eye_height = , -- (optional) + -- -- suspend client side animations while this one is active (optional) + -- override_local = + -- }, + stand = ..., lay = ..., walk = ..., mine = ..., walk_mine = ..., -- required animations + sit = ... -- used by boats and other MTG mods + }, + -- Default object properties, see lua_api.txt + visual_size = {x = 1, y = 1}, + collisionbox = {-0.3, 0.0, -0.3, 0.3, 1.7, 0.3}, + stepheight = 0.6, + eye_height = 1.47 + } diff --git a/mods/player_api/README.md b/mods/player_api/README.md new file mode 100644 index 00000000..13b72eab --- /dev/null +++ b/mods/player_api/README.md @@ -0,0 +1,19 @@ +# `player_api` compability layer for Repixture + +This mod is the Repixture implementation of `player_api` originally from Minetest Game. +It is API-compatible with Minetest Game's `player_api` from Minetest Game 5.8.0. +Technically, it is just a wrapper around `rp_player`, provided for compability. + +Mod developers can use this mod to handle player-related stuff and should be enough +for most purposes. + +For advanced player model features specific to Repixture, you may use `rp_player` instead + +## Credits + +The API documentation is copied from from Minetest Game 5.8.0. +originally by celeron55, Perttu Ahola (LGPLv2.1+), +continued by Minetest developers and contributors (LGPLv2.1+), +changed for Repixture by Wuzzy (LGPLv2.1+). + +Everything else written by Wuzzy (LGBPLv2.1+). diff --git a/mods/player_api/init.lua b/mods/player_api/init.lua new file mode 100644 index 00000000..c51509ce --- /dev/null +++ b/mods/player_api/init.lua @@ -0,0 +1,13 @@ +player_api = {} + +player_api.register_model = rp_player.player_register_model + +player_api.set_model = rp_player.player_set_model +player_api.get_animation = rp_player.player_get_animation +player_api.set_animation = rp_player.player_set_animation +player_api.get_textures = rp_player.player_get_textures +player_api.set_textures = rp_player.player_set_textures +player_api.globalstep = rp_player.globalstep + +player_api.player_attached = rp_player.player_attached +player_api.registered_models = rp_player.registered_models diff --git a/mods/player_api/mod.conf b/mods/player_api/mod.conf new file mode 100644 index 00000000..224f43d7 --- /dev/null +++ b/mods/player_api/mod.conf @@ -0,0 +1,3 @@ +name = player_api +depends = rp_player +description = Compability layer for player API mod from Minetest Game