Velocity

Movement velocity vector for entities. Used for knockback, launches, dashes, and physics-based movement.

Access

Velocity velocity = store.getComponent(ref, Velocity.getComponentType());

Basic Operations

// get current velocity
Vector3d vel = velocity.getVelocity();
double speed = velocity.getSpeed();  // velocity.length()

// get individual axes
double x = velocity.getX();
double y = velocity.getY();
double z = velocity.getZ();

// set velocity (replaces current)
velocity.set(x, y, z);
velocity.set(new Vector3d(x, y, z));

// add force (accumulates)
velocity.addForce(x, y, z);
velocity.addForce(new Vector3d(x, y, z));

// clear velocity
velocity.setZero();

Instructions (Recommended for Players)

For player entities, use the instruction system. Instructions are queued and processed by the velocity system, which handles network synchronization.

// launch player upward
velocity.addInstruction(
    new Vector3d(0, 15, 0),
    null,  // VelocityConfig (optional)
    ChangeVelocityType.Set
);

// add knockback force
velocity.addInstruction(
    knockbackDirection,
    velocityConfig,
    ChangeVelocityType.Add
);

ChangeVelocityType

Type	Effect
Set	Replaces current velocity
Add	Adds to current velocity

VelocityConfig

Controls how velocity decays over time:

Field	Default	Description
groundResistance	0.82	Velocity multiplier on ground
groundResistanceMax	0.0	Max resistance above threshold
airResistance	0.96	Velocity multiplier in air
airResistanceMax	0.0	Max resistance above threshold
threshold	1.0	Speed where resistance transitions to max
style	Linear	Transition style (Linear or Exp)

Lower resistance = faster decay. A value of 0.82 means velocity is multiplied by 0.82 each tick when on ground.

When speed exceeds threshold, resistance transitions from base to max value based on style.

Examples

Launch Pad

Velocity velocity = store.getComponent(ref, Velocity.getComponentType());
velocity.addInstruction(
    new Vector3d(0, 20, 0),  // launch upward
    null,
    ChangeVelocityType.Set
);

Knockback

// calculate knockback direction from attacker to target
Vector3d knockback = targetPos.clone().sub(attackerPos).normalize();
knockback.setY(0.4);  // add upward component
knockback.scale(10);  // knockback strength

Velocity velocity = store.getComponent(targetRef, Velocity.getComponentType());
velocity.addInstruction(knockback, null, ChangeVelocityType.Add);

Dash Ability

// get player's look direction
HeadRotation head = store.getComponent(ref, HeadRotation.getComponentType());
Vector3d direction = head.getDirection();
direction.setY(0);  // horizontal only
direction.normalize().scale(15);

Velocity velocity = store.getComponent(ref, Velocity.getComponentType());
velocity.addInstruction(direction, null, ChangeVelocityType.Set);

Reading Velocity (Fall Damage)

Velocity velocity = store.getComponent(ref, Velocity.getComponentType());
double fallSpeed = Math.abs(velocity.getY());

if (fallSpeed > fallDamageThreshold) {
    // apply fall damage
}

Client vs Server Velocity

The component tracks separate velocities:

Method	Purpose
getVelocity()	Server-side velocity
getClientVelocity()	Client-predicted velocity
setClient(x, y, z)	Set client velocity

For player entities, changes are synced via the ChangeVelocity packet (ID: 163).

Processing Order

Velocity changes are processed through ECS systems:

1. Systems queue instructions via addInstruction()
2. GenericVelocityInstructionSystem processes non-player entities
3. PlayerVelocityInstructionSystem sends packets to player clients
4. Instructions are cleared after processing