Modding:Entity Behavior controlledphysics

This entity behavior adds physics to an entity that can move on its own, which includes all mobs. It is responsible for updating the entity position based on the entity's velocity, and processing terrain collisions.

Internally the behavior also processes a list of physics modules. These modules cannot be disabled with json, nor can new modules be added with just json. However, some parameters can be adjusted in json for the modules.

The physics system runs at 30 ticks per second. If the overall server is ticking at less than that rate, extra physics ticks are added to compensate. This is important, because in several places the acceleration is simply added to the velocity, instead of using a tick rate independent quadratic formula to determine the entity position.

However, it appears the system was originally designed to run at 60 ticks per second, because in the code the unit for all velocities is blocks per 60-second-tick. That is: blocks/(seconds/60).

Modules

Note that the in the code, the dt passed to DoApply is always the time for a single physics tick: 1/30.

PModuleWind

This module is only enabled if the windAffectedEntityMovement world config is enabled (off by default).

It causes the wind to blow the entity around when it tries to move on the ground. Specifically, it adds a wind force to the entity's velocity.

The wind force is 0 below the world surface (below the highest block in that xz position).

PModuleOnGround

When the entity is on the ground (and for 0.15 seconds after leaving the ground), this module applies the entity's acceleration (called motionDelta in the code) onto their velocity. It also adjusts the acceleration based on the entity's control force (direction it is trying to move). This module takes multiple factors into account to decide the strength of the control force:

• Friction of the block below the entity (specifically the dragmultiplier) - reduces how much of the control force is applied to the acceleration. Used for ice blocks.
• WalkSpeedMultiplier of below block and inside block (for snow) - adjusts the strength of the control force. Used for snow and road blocks.
• Whether the sneak or sprint keys are held - adjusts the strength of the control force.
• Whether the entity feet are in liquid (but not swimming) - reduces the control force strength.
• The armor walk speed (player only) - reduces the control force strength.

Acceleration is added to the velocity on every frame. The force is an acceleration. So without additional drag, the acceleration would build up an unreasonable velocity. To counter this, the overall velocity is reduced by groundDragFactor on every frame.

Properties

groundDragFactor: (float, default 1)

multiplier for the default ground multiplier of 0.3. Setting this close to 0 causes the entity to move like a rocket ship, where it can accelerate to huge velocities, and it has to accelerate in the opposite direction to stop. Setting this above 1 improves the responsiveness of the controls, but also reduces the total velocity. Note that PModuleMotionDrag applies drag on top of this.

PModuleInLiquid

Applies the flowing water vector onto the entity. Applies the control force when the entity is swimming.

PModuleInAir

Applies the control force when the player is flying, free falling, or climbing.

Properties

wallDragFactor: (float, default 1)

friction while the player is climbing ladders.

airMovingStrength: (float, default 0.05)

multiplier for the control force while the player is free falling. This controls how much the player can adjust their velocity while falling.

PModuleGravity

Applies a downward gravity force to the entity motion. Gravity does not apply in several cases:

• Fish in water - based on the entity habitat and whether it is swimming
• Birds - based on entity habitat
• Flying in creative mode
• Climbing a ladder

The overall gravity is set by the GravityPerSecond global constant (not adjustable), which is set to 0.37. This value can be changed per entity with the gravityFactor property. The gravity is divided by 3 if the entity is in water.

The gravity force is increased if the entity is already falling. This may be what Tyron calls 'coyote time', where the entity sort of floats for the first part of the jump, then falls down quickly.

Then that gravity factor/30 is added to the entity velocity on every tick. The entity velocity is in blocks per 60 second tick.

A simulation showed that for the default gravity and air drag, the terminal velocity of entities is -39.91 blocks per second.

Properties

gravityFactor: (float, default 1)

multiplies the global gravity constant for this entity.

PModuleMotionDrag

Applies water drag while the entity is in liquid, and air drag otherwise (including when it is on land).

Properties

waterDragFactor: (float, default 1)

multiplies the drag of the entity in water. Big values cause it to slow down faster.

airDragFactor: (float, default 1)

multiplies the air and land drag of the entity. Big values cause it to slow down faster.

PModuleKnockback

Each time the entity is knocked back, it adds the knockback velocity (stored in the kbdirX, kbdirY, and kbdirZ entity attributes) to the entity velocity. This force is all applied for exactly 1 frame per knockback. The knockback lasts until the control and drag forces overcome the velocity that was added.

Behavior properties

stepHeight: (float, default 0.6)

If the entity runs into a block, and they are up to this far from the top of the block, then they are placed onto the block instead of falling down the side.

Additionally the physics module properties are read from an optional dictionary in the entity attributes called physics.

Wondering where some links have gone?
The modding navbox is going through some changes! Check out Navigation Box Updates for more info and help finding specific pages.