minetest_playerphysics-cd2025/API.md

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.

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.