MinecraftMotionTools 1.8.7

A library to compute entities' motion in Minecraft.

MinecraftMotionTools

MinecraftMotionTools is a collection of functions whose purpose is to ease prediction of the velocity and the position of entities simulated into Minecraft.

How does it work?

Minecraft updates velocity in a different way from real-physics objects, plus it complicates everything just by being a video game and having to update the values in a finite unit of time (the tick).

Minecraft's Wiki got some information about how it works, but here is the reasoning behind the velocity equations.

Another complication comes from what I, in the code, refer to as acceleration drag, which initially required forking the formulas for every different case (see old sheet), before I decided to generalize the formulas, introducing the coefficient k.

Acceleration drag works the following way:

$\text{position}_{new}=\text{position}_{old}+\text{velocity}-k\cdot\text{acceleration}$

Finally, here is the formulas' sheet I wrote down. Take in mind that a fair amount of them make use of Lambert's W function.

For the acceleration's formulas refer to this sheet instead.

Entities' parameter table

Type	Acceleration	Vertical drag	Horizontal drag	Applies drag	k coefficient
Players, mobs and armor stands	0.08	0.02	0.09	After	0
Entities with slow falling	0.01	0.02	0.09	After	0
Items, falling blocks and TNTs	0.04	0.02	0.02	After	1
Minecarts	0.04	0.05	0.05	After	1
Boats	0.04	0	0.10	-	1
Thrown eggs, snowballs and ender pearls	0.03	0.01	0.01	Before	0
Thrown potions	0.05	0.01	0.01	Before	0
Thrown experience bottles	0.07	0.01	0.01	Before	0
Experience orbs	0.03	0.02	0.02	After	1
Thrown fishing bobbers	0.03	0.08	0.08	After	1
Llama spit	0.06	0.01	0.01	Before	0
Fired arrows and thrown tridents	0.05	0.01	0.01	Before	0
Fireballs, wither skulls and dragon fireballs	0.10	0.05	0.05	After	0
Dangerous wither skulls	0.10	0.27	0.27	After	0
Wind charges	0.10	0	0	-	0

NOTES:

• For fireballs and alike, use negative acceleration (see here why).
• Players, mobs and armor stands whose OnGround property is set to 1 have an horizontal drag force of 0.454.
• The maximum general velocity value is 10. Any greater value is reset to 0.
• Even though 10 is the maximum velocity that can be set, entities with 0 drag force can gain infinite velocity due to acceleration.
• Minecarts have a maximum horizontal velocity of 0.4. Any greater value is reset to that number.
• Boats' horizontal position gets updated using next tick's velocity instead of the current one.

Function list

v0: initial velocity
t: ticks passed
v: current velocity
p: current relative position
h: maximum height
a: acceleration
d: drag force
after: whether drag is applied after or before gravity acceleration
k: acceleration drag coefficient

Default parameters are set to Falling Blocks.

Name	Required arguments	Optional arguments	Brief description
v_from_t	v0, t	a, d, after	Retrieves velocity from an initial velocity and the time that has passed, in ticks.
p_from_t	v0, t	a, d, after, k	Retrieves relative position from an initial velocity and the time that has passed, in ticks.
max_height_tick_from_v0	v0	a, d, after, k	Retrieves the time in ticks the maximum relative height is reached.
max_height_from_v0	v0	a, d, after, k	Retrieves the maximum relative height reached (using integer approximation of the tick).
v0_from_max_height	h	a, d, after, k	Retrieves a tuple of up to 2 solutions, each one belonging to the possible arcs with the specified height.
v0_from_v_t	v, t	a, d, after	Retrieves initial velocity from a pair of current velocity and time passed, in ticks.
v0_from_p_t	p, t	a, d, after, k	Retrieves initial velocity from a pair of current relative position and time passed, in ticks.
t_from_v0_v	v0, v	a, d, after	Retrieves the time passed (in ticks) since velocity was v0 to become v.
t_from_v0_p	v0, p	a, d, after, k	Retrieves the time passed (in ticks) to reach the relative position specified.
v0_t_from_v_p	v, p	a, d, after, k	Retrieves a pair of initial velocity and time passed (in ticks) to reach the state of current velocity/position specified.

Acceleration related functions

These functions retrieve the acceleration from 2 state pairs of the wanted trajectory.
Functions involving a velocity/position state pair are not guaranteed to retrieve all the solutions, though that should be a limit case.
If drag is set to 0, all the functions will use safe algorithms, meaning iterative approximation algorithms won't be used.

Default parameters are set to Fireballs.

Name	Required arguments	Optional arguments	Brief description
a_from_double_v_t	(v1, t1), (v2, t2)	d, after	Retrieves acceleration from 2 states of velocity/time.
a_from_double_p_t	(p1, t1), (p2, t2)	d, after, k	Retrieves acceleration from 2 states of position/time.
a_from_double_v_p	(v1, p1), (v2, p2)	d, after, k	Attempts to retrieve the acceleration from 2 states of velocity/position.
a_from_v_t_p_t	(v1, t1), (p2, t2)	d, after, k	Retrieves acceleration from 2 states of velocity/time and position/time.
a_from_v_t_v_p	(v1, t1), (v2, p2)	d, after, k	Attempts to retrieve the acceleration from 2 states of velocity/time and velocity/position.
a_from_p_t_v_p	(p1, t1), (v2, p2)	d, after, k	Attempts to retrieve the acceleration from 2 states of position/time and velocity/position.

How to install?

Install Python 3 and pip, then run

pip install MinecraftMotionTools

To update the package to its latest version run

pip install --upgrade MinecraftMotionTools

How to use?

Check some of the code examples for common use cases.