mirror of
https://git.minetest.land/VoxeLibre/VoxeLibre.git
synced 2025-03-11 06:07:44 +01:00
Merge pull request 'Update playerphysics to 1.1.0 (upstream mod changes)' (#4836) from playerphysics_upstream into master
Reviewed-on: https://git.minetest.land/VoxeLibre/VoxeLibre/pulls/4836 Reviewed-by: kno10 <kno10@noreply.git.minetest.land>
This commit is contained in:
the-real-herowl
commit
7456eba0f5
5 changed files with 135 additions and 95 deletions
103
mods/PLAYER/playerphysics/API.md
Normal file
103
mods/PLAYER/playerphysics/API.md
Normal file
|
|
@ -0,0 +1,103 @@
|
|||
# Player Physics API Documentation
|
||||
This document explains how to use the Player Physics API as a developer.
|
||||
|
||||
## Quick start
|
||||
Let's say you have a mod `example` and want to double the speed of the player (i.e. multiply it by a factor of 2), but you also don't want to break other mods that might touch the speed.
|
||||
|
||||
Previously, you might have written something like this:
|
||||
|
||||
`player:set_physics_override({speed=2})`
|
||||
|
||||
However, your mod broke down as soon the mod `example2` came along, which wanted to increase the speed by 50%. In the real game, the player speed randomly switched from 50% and 200% which was a very annoying bug.
|
||||
|
||||
In your `example` mod, you can replace the code with this:
|
||||
|
||||
`playerphysics.add_physics_factor(player, "speed", "my_double_speed", 2)`
|
||||
|
||||
Where `"my_double_speed` is an unique ID for your speed factor.
|
||||
|
||||
Now your `example` mod is interoperable! And now, of course, the `example2` mod has to be updated in a similar fashion.
|
||||
|
||||
## Precondition
|
||||
There is only one precondition to using this mod, but it is important:
|
||||
|
||||
Mods *MUST NOT* call `set_physics_override` directly for numerical values. Instead, to modify player physics, all mods that touch player physics have to use this API.
|
||||
|
||||
|
||||
|
||||
|
||||
## Functions
|
||||
### `playerphysics.add_physics_factor(player, attribute, id, value)`
|
||||
Adds a factor for a player physic and updates the player physics immediately.
|
||||
|
||||
#### Parameters
|
||||
* `player`: Player object
|
||||
* `attribute`: Which of the physical attributes to change. Any of the numeric values of `set_physics_override` (e.g. `"speed"`, `"jump"`, `"gravity"`)
|
||||
* `id`: Unique identifier for this factor. Identifiers are stored on a per-player per-attribute type basis
|
||||
* `value`: The factor to add to the list of products
|
||||
|
||||
If a factor for the same player, attribute and `id` already existed, it will be overwritten.
|
||||
|
||||
|
||||
|
||||
### `playerphysics.remove_physics_factor(player, attribute, id)`
|
||||
Removes the physics factor of the given ID and updates the player's physics.
|
||||
|
||||
#### Parameters
|
||||
Same as in `playerphysics.add_physics_factor`, except there is no `value` argument.
|
||||
|
||||
|
||||
|
||||
### `playerphysics.get_physics_factor(player, attribute, id)`
|
||||
Returns the current physics factor of the given ID, if it exists.
|
||||
If the ID exists, returns a number. If it does not exist, returns nil.
|
||||
|
||||
Note a missing physics factor is mathematically equivalent to a factor of 1.
|
||||
|
||||
#### Parameters
|
||||
Same as in `playerphysics.add_physics_factor`, except there is no `value` argument.
|
||||
|
||||
|
||||
|
||||
## Examples
|
||||
### Speed changes
|
||||
Let's assume this mod is used by 3 different mods all trying to change the speed:
|
||||
Potions, Exhaustion and Electrocution.
|
||||
Here's what it could look like:
|
||||
|
||||
Potions mod:
|
||||
|
||||
playerphysics.add_physics_factor(player, "speed", "run_potion", 2)
|
||||
|
||||
Exhaustion mod:
|
||||
|
||||
playerphysics.add_physics_factor(player, "jump", "exhausted", 0.75)
|
||||
|
||||
Electrocution mod:
|
||||
|
||||
playerphysics.add_physics_factor(player, "jump", "shocked", 0.9)
|
||||
|
||||
When the 3 mods have done their change, the real player speed is simply the product of all factors, that is:
|
||||
|
||||
2 * 0.75 * 0.9 = 1.35
|
||||
|
||||
The final player speed is thus 135%.
|
||||
|
||||
### Speed changes, part 2
|
||||
|
||||
Let's take the example above.
|
||||
Now if the Electrocution mod is done with shocking the player, it just needs to call:
|
||||
|
||||
playerphysics.remove_physics_factor(player, "jump", "shocked")
|
||||
|
||||
The effect is now gone, so the new player speed will be:
|
||||
|
||||
2 * 0.75 = 1.5
|
||||
|
||||
### Sleeping
|
||||
To simulate sleeping by preventing all player movement, this can be done with this easy trick:
|
||||
|
||||
playerphysics.add_physics_factor(player, "speed", "sleeping", 0)
|
||||
playerphysics.add_physics_factor(player, "jump", "sleeping", 0)
|
||||
|
||||
This works regardless of the other factors because 0 times anything equals 0.
|
||||
9
mods/PLAYER/playerphysics/LICENSE.txt
Normal file
9
mods/PLAYER/playerphysics/LICENSE.txt
Normal file
|
|
@ -0,0 +1,9 @@
|
|||
The MIT License (MIT)
|
||||
|
||||
Copyright © 2024 Wuzzy
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
|
||||
|
||||
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
|
||||
|
||||
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
||||
|
|
@ -1,12 +1,12 @@
|
|||
# Player Physics API.
|
||||
# Player Physics API
|
||||
|
||||
Version: 1.0.0
|
||||
Version: 1.1.0
|
||||
|
||||
This mod makes it possible for multiple mods to modify player physics (speed, jumping strength, gravity) without conflict.
|
||||
|
||||
## Introduction
|
||||
### For players
|
||||
Mods and games in Minetest can set physical attributes of players, such as speed and jump strength. For example, player speed could be set to 200%. But the way this works makes it difficult for multiple mods to *modify* physical attributes without leading to conflicts, problems and hilarious bugs, like speed that changes often to nonsense values.
|
||||
Mods and games in Luanti can set physical attributes of players, such as speed and jump strength. For example, player speed could be set to 200%. But the way this works makes it difficult for multiple mods to *modify* physical attributes without leading to conflicts, problems and hilarious bugs, like speed that changes often to nonsense values.
|
||||
|
||||
The Player Physics API aims to resolve this conflict by providing a “common ground” for mods to work together in this regard.
|
||||
|
||||
|
|
@ -19,98 +19,13 @@ Of course, not all mods need the Player Physics API. Mods that don't touch playe
|
|||
The rest of this document is directed at developers.
|
||||
|
||||
### For developers
|
||||
The function `set_physics_override` from the Minetest Lua API allows mod authors to override physical attributes of players, such as speed or jump strength.
|
||||
The function `set_physics_override` from the Luanti Lua API allows mod authors to override physical attributes of players, such as speed or jump strength.
|
||||
|
||||
This function works fine as long there is only one mod that sets a particular physical attribute at a time. However, as soon as at least two different mods (that do not know each other) try to change the same player physics attribute using only this function, there will be conflicts as each mod will undo the change of the other mod, as the function sets a raw value. A classic race condition occurs. This is the case because the mods fail to communicate with each other.
|
||||
|
||||
This mod solves the problem of conflicts. It bans the concept of “setting the raw value directly” and replaces it with the concept of factors that mods can add and remove for each attribute. The real physical player attribute will be the product of all active factors.
|
||||
|
||||
## Quick start
|
||||
Let's say you have a mod `example` and want to double the speed of the player (i.e. multiply it by a factor of 2), but you also don't want to break other mods that might touch the speed.
|
||||
See `API.md` for the API documentation.
|
||||
|
||||
Previously, you might have written something like this:
|
||||
|
||||
`player:set_physics_override({speed=2})`
|
||||
|
||||
However, your mod broke down as soon the mod `example2` came along, which wanted to increase the speed by 50%. In the real game, the player speed randomly switched from 50% and 200% which was a very annoying bug.
|
||||
|
||||
In your `example` mod, you can replace the code with this:
|
||||
|
||||
`playerphysics.add_physics_factor(player, "speed", "my_double_speed", 2)`
|
||||
|
||||
Where `"my_double_speed` is an unique ID for your speed factor.
|
||||
|
||||
Now your `example` mod is interoperable! And now, of course, the `example2` mod has to be updated in a similar fashion.
|
||||
|
||||
## Precondition
|
||||
There is only one precondition to using this mod, but it is important:
|
||||
|
||||
Mods *MUST NOT* call `set_physics_override` directly for numerical values. Instead, to modify player physics, all mods that touch player physics have to use this API.
|
||||
|
||||
## Functions
|
||||
### `playerphysics.add_physics_factor(player, attribute, id, value)`
|
||||
Adds a factor for a player physic and updates the player physics immediately.
|
||||
|
||||
#### Parameters
|
||||
* `player`: Player object
|
||||
* `attribute`: Which of the physical attributes to change. Any of the numeric values of `set_physics_override` (e.g. `"speed"`, `"jump"`, `"gravity"`)
|
||||
* `id`: Unique identifier for this factor. Identifiers are stored on a per-player per-attribute type basis
|
||||
* `value`: The factor to add to the list of products
|
||||
|
||||
If a factor for the same player, attribute and `id` already existed, it will be overwritten.
|
||||
|
||||
### `playerphysics.remove_physics_factor(player, attribute, id)`
|
||||
Removes the physics factor of the given ID and updates the player's physics.
|
||||
|
||||
#### Parameters
|
||||
Same as in `playerphysics.add_physics_factor`, except there is no `value` argument.
|
||||
|
||||
## Examples
|
||||
### Speed changes
|
||||
Let's assume this mod is used by 3 different mods all trying to change the speed:
|
||||
Potions, Exhaustion and Electrocution.
|
||||
Here's what it could look like:
|
||||
|
||||
Potions mod:
|
||||
```
|
||||
playerphysics.add_physics_factor(player, "speed", "run_potion", 2)
|
||||
```
|
||||
|
||||
Exhaustion mod:
|
||||
```
|
||||
playerphysics.add_physics_factor(player, "jump", "exhausted", 0.75)
|
||||
```
|
||||
|
||||
Electrocution mod:
|
||||
```
|
||||
playerphysics.add_physics_factor(player, "jump", "shocked", 0.9)
|
||||
```
|
||||
|
||||
When the 3 mods have done their change, the real player speed is simply the product of all factors, that is:
|
||||
|
||||
2 * 0.75 * 0.9 = 1.35
|
||||
|
||||
The final player speed is thus 135%.
|
||||
|
||||
### Speed changes, part 2
|
||||
|
||||
Let's take the example above.
|
||||
Now if the Electrocution mod is done with shocking the player, it just needs to call:
|
||||
|
||||
```
|
||||
playerphysics.remove_physics_factor(player, "jump", "shocked")
|
||||
```
|
||||
|
||||
The effect is now gone, so the new player speed will be:
|
||||
|
||||
2 * 0.75 = 1.5
|
||||
|
||||
### Sleeping
|
||||
To simulate sleeping by preventing all player movement, this can be done with this easy trick:
|
||||
|
||||
```
|
||||
playerphysics.add_physics_factor(player, "speed", "sleeping", 0)
|
||||
playerphysics.add_physics_factor(player, "jump", "sleeping", 0)
|
||||
```
|
||||
|
||||
This works regardless of the other factors because 0 times anything equals 0.
|
||||
## License
|
||||
This mod is free software, released under the MIT License (see `LICENSE.txt`).
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
playerphysics = {}
|
||||
|
||||
local function calculate_attribute_product(player, attribute)
|
||||
local a = minetest.deserialize(player:get_meta():get_string("playerphysics:physics"))
|
||||
local a = minetest.deserialize(player:get_meta():get_string("playerphysics:physics"), true)
|
||||
local product = 1
|
||||
if a == nil or a[attribute] == nil then
|
||||
return product
|
||||
|
|
@ -17,7 +17,7 @@ end
|
|||
|
||||
function playerphysics.add_physics_factor(player, attribute, id, value)
|
||||
local meta = player:get_meta()
|
||||
local a = minetest.deserialize(meta:get_string("playerphysics:physics"))
|
||||
local a = minetest.deserialize(meta:get_string("playerphysics:physics"), true)
|
||||
if a == nil then
|
||||
a = { [attribute] = { [id] = value } }
|
||||
elseif a[attribute] == nil then
|
||||
|
|
@ -32,7 +32,7 @@ end
|
|||
|
||||
function playerphysics.remove_physics_factor(player, attribute, id)
|
||||
local meta = player:get_meta()
|
||||
local a = minetest.deserialize(meta:get_string("playerphysics:physics"))
|
||||
local a = minetest.deserialize(meta:get_string("playerphysics:physics"), true)
|
||||
if a == nil or a[attribute] == nil then
|
||||
-- Nothing to remove
|
||||
return
|
||||
|
|
@ -43,3 +43,15 @@ function playerphysics.remove_physics_factor(player, attribute, id)
|
|||
local raw_value = calculate_attribute_product(player, attribute)
|
||||
player:set_physics_override({[attribute] = raw_value})
|
||||
end
|
||||
|
||||
function playerphysics.get_physics_factor(player, attribute, id)
|
||||
local meta = player:get_meta()
|
||||
local a = minetest.deserialize(meta:get_string("playerphysics:physics"), true)
|
||||
if a == nil then
|
||||
return nil
|
||||
elseif a[attribute] == nil then
|
||||
return nil
|
||||
else
|
||||
return a[attribute][id]
|
||||
end
|
||||
end
|
||||
|
|
|
|||
|
|
@ -1,3 +1,4 @@
|
|||
name = playerphysics
|
||||
author = Wuzzy
|
||||
title = Player Physics API
|
||||
description = This mod makes it possible for multiple mods to modify player physics (speed, jumping strength, gravity) without conflict.
|
||||
|
|
|
|||
Loading…
Reference in a new issue