Player Movement

MovementManager

Player movement is controlled through the MovementManager component, which holds a MovementSettings instance with 61 configurable parameters.

MovementManager movement = store.getComponent(ref, MovementManager.getComponentType());
MovementSettings settings = movement.getSettings();

See Entity Components for details on store and component access patterns.

Common Use Cases

Enable/Disable Flight

MovementSettings settings = movement.getSettings();
settings.canFly = true;

// send to client
Player player = store.getComponent(ref, Player.getComponentType());
movement.update(player.getPlayerRef().getPacketHandler());

Modify Speed

MovementSettings settings = movement.getSettings();

// base walking speed (default: 5.5)
settings.baseSpeed = 8.0f;

// sprint multiplier (default: 1.65)
settings.forwardSprintSpeedMultiplier = 2.0f;

movement.update(player.getPlayerRef().getPacketHandler());

Modify Jump

MovementSettings settings = movement.getSettings();

// jump force (default: 11.8)
settings.jumpForce = 20.0f;

movement.update(player.getPlayerRef().getPacketHandler());

Reset to Defaults

// reset to world defaults and sync to client
movement.resetDefaultsAndUpdate(ref, store);

// or reset without syncing
movement.applyDefaultSettings();

Reading Movement State

To check what a player is currently doing (flying, sprinting, crouching, etc.), read the MovementStatesComponent:

MovementStatesComponent statesComponent = store.getComponent(ref,
    MovementStatesComponent.getComponentType());
MovementStates states = statesComponent.getMovementStates();

if (states.flying) {
    // player is currently in flight
}
if (states.sprinting) {
    // player is sprinting
}

Available States

All fields are public booleans on MovementStates:

Field	Description
`idle`	Not moving
`horizontalIdle`	No horizontal movement
`jumping`	Currently jumping
`flying`	Currently in flight
`walking`	Walking (slow movement)
`running`	Running (normal movement)
`sprinting`	Sprinting (fast movement)
`crouching`	Crouching
`forcedCrouching`	Forced crouch (e.g., under low ceiling)
`falling`	Falling
`climbing`	Climbing a surface
`inFluid`	In fluid (water/lava)
`swimming`	Swimming
`swimJumping`	Jumping while swimming
`onGround`	On solid ground
`mantling`	Mantling an edge
`sliding`	Sliding
`mounting`	Mounting an entity
`rolling`	Rolling
`sitting`	Sitting
`gliding`	Gliding
`sleeping`	Sleeping

MovementSettings Reference

All fields are public and directly modifiable on MovementSettings.

Ground Movement

Field	Default	Description
`baseSpeed`	5.5	Base movement speed
`acceleration`	0.1	Movement acceleration
`forwardRunSpeedMultiplier`	1.0	Forward run speed multiplier
`backwardRunSpeedMultiplier`	0.65	Backward run speed multiplier
`strafeRunSpeedMultiplier`	0.8	Strafe run speed multiplier
`forwardSprintSpeedMultiplier`	1.65	Sprint speed multiplier
`forwardWalkSpeedMultiplier`	0.3	Walk speed multiplier
`backwardWalkSpeedMultiplier`	0.3	Backward walk multiplier
`strafeWalkSpeedMultiplier`	0.3	Strafe walk multiplier
`forwardCrouchSpeedMultiplier`	0.55	Crouch speed multiplier
`backwardCrouchSpeedMultiplier`	0.4	Backward crouch multiplier
`strafeCrouchSpeedMultiplier`	0.45	Strafe crouch multiplier

Jumping

Field	Default	Description
`jumpForce`	11.8	Jump force
`swimJumpForce`	10.0	Jump force while swimming
`fallJumpForce`	7.0	Jump force when falling
`jumpBufferDuration`	0.3	Jump buffer window (seconds)
`jumpBufferMaxYVelocity`	3.0	Max Y velocity for jump buffer
`variableJumpFallForce`	35.0	Fall force for variable jump height

Flight

Field	Default	Description
`canFly`	false*	Whether player can fly (*true in Creative)
`horizontalFlySpeed`	10.32	Horizontal flight speed
`verticalFlySpeed`	10.32	Vertical flight speed

Air Control

Field	Default	Description
`airSpeedMultiplier`	1.0	Air movement speed multiplier
`airDragMin`	0.96	Minimum air drag
`airDragMax`	0.995	Maximum air drag
`airDragMinSpeed`	6.0	Speed for minimum drag
`airDragMaxSpeed`	10.0	Speed for maximum drag
`airFrictionMin`	0.02	Minimum air friction
`airFrictionMax`	0.045	Maximum air friction
`airFrictionMinSpeed`	6.0	Speed for minimum friction
`airFrictionMaxSpeed`	10.0	Speed for maximum friction
`airControlMinSpeed`	0.0	Speed for minimum air control
`airControlMaxSpeed`	3.0	Speed for maximum air control
`airControlMinMultiplier`	0.0	Minimum air control
`airControlMaxMultiplier`	3.13	Maximum air control
`comboAirSpeedMultiplier`	1.05	Air speed during combos

Climbing

Field	Default	Description
`climbSpeed`	0.035	Climb speed
`climbSpeedLateral`	0.035	Lateral climb speed
`climbUpSprintSpeed`	0.045	Sprint climb up speed
`climbDownSprintSpeed`	0.055	Sprint climb down speed

Sliding

Field	Default	Description
`minSlideEntrySpeed`	8.5	Minimum speed to start sliding
`slideExitSpeed`	2.5	Speed at which slide ends

Rolling

Field	Default	Description
`minFallSpeedToEngageRoll`	21.0	Minimum fall speed to trigger roll
`maxFallSpeedToEngageRoll`	31.0	Maximum fall speed for roll
`rollStartSpeedModifier`	2.5	Speed modifier at roll start
`rollExitSpeedModifier`	1.5	Speed modifier at roll exit
`rollTimeToComplete`	0.9	Roll duration (seconds)

Auto-Jump

Field	Default	Description
`autoJumpDisableJumping`	true	Disable manual jump during auto-jump
`autoJumpObstacleSpeedLoss`	0.95	Speed loss on auto-jump
`autoJumpObstacleSprintSpeedLoss`	0.75	Speed loss when sprinting
`autoJumpObstacleEffectDuration`	0.2	Effect duration (seconds)
`autoJumpObstacleSprintEffectDuration`	0.1	Sprint effect duration (seconds)
`autoJumpObstacleMaxAngle`	45.0	Maximum angle for auto-jump

Physics

Field	Default	Description
`mass`	1.0	Player mass (from PhysicsValues)
`dragCoefficient`	0.5	Drag coefficient (from PhysicsValues)
`invertedGravity`	false	Invert gravity (from PhysicsValues)
`velocityResistance`	0.242	Velocity resistance
`collisionExpulsionForce`	0.04	Force when colliding

Fall Effects

Field	Default	Description
`fallEffectDuration`	0.6	Fall effect duration (seconds)
`fallMomentumLoss`	0.1	Momentum loss on landing

Wish Direction

Movement prediction parameters for client-side smoothing.

Field	Default	Description
`wishDirectionGravityX`	0.5	Horizontal direction gravity
`wishDirectionGravityY`	0.5	Vertical direction gravity
`wishDirectionWeightX`	0.5	Horizontal direction weight
`wishDirectionWeightY`	0.5	Vertical direction weight

Speed Limits

Field	Default	Description
`maxSpeedMultiplier`	1000.0	Maximum speed multiplier cap
`minSpeedMultiplier`	0.1	Minimum speed multiplier cap

PhysicsValues Component

For physics properties (mass, drag, gravity), use the separate PhysicsValues component:

PhysicsValues physics = store.getComponent(ref, PhysicsValues.getComponentType());

// modify physics
physics.scale(2.0f);  // double all values

// or replace entirely
physics.replaceValues(new PhysicsValues(2.0, 0.8, false));

// reset to defaults
physics.resetToDefault();

Movement Presets

Movement configurations can be defined as JSON assets and applied via MovementConfig:

// get preset from asset store
MovementConfig config = MovementConfig.getAssetMap().getAsset("my_movement_preset");

if (config != null) {
    MovementManager movement = store.getComponent(ref, MovementManager.getComponentType());
    Player player = store.getComponent(ref, Player.getComponentType());
    PhysicsValues physics = store.getComponent(ref, PhysicsValues.getComponentType());

    // apply preset as new defaults
    movement.setDefaultSettings(config.toPacket(), physics, player.getGameMode());
    movement.applyDefaultSettings();
    movement.update(player.getPlayerRef().getPacketHandler());
}

The default preset ID is "BuiltinDefault". The active preset can be set per-world via GameplayConfig - Player.

Server-Side Only Fields

MovementConfig has additional fields that affect fall damage but aren’t synced to clients. Fall damage is applied through the damage pipeline with DamageCause.FALL.

Field	Default	Description
`fallDamagePartialMitigationPercent`	33.0	Percent of fall damage mitigated by rolling
`maxFallSpeedRollFullMitigation`	25.0	Max fall speed for full roll mitigation

These are only configurable via JSON presets, not at runtime via MovementSettings.