Physics System Overview

Physics System Overview

The Physics System handles entity movement, collision detection, and physical simulation. It uses an ECS-based approach with velocity components, collision detection modules, and configurable hitboxes.

Package Location

• Physics: com.hypixel.hytale.server.core.modules.physics
• Collision: com.hypixel.hytale.server.core.modules.collision
• Hitbox: com.hypixel.hytale.server.core.modules.entity.hitboxcollision
• Velocity: com.hypixel.hytale.server.core.modules.splitvelocity

Architecture

flowchart TB
    subgraph Physics["Physics System"]
        subgraph Components["Components"]
            Velocity["Velocity<br/>Component"]
            Collision["Collision<br/>Module"]
            Hitbox["Hitbox<br/>Component"]
        end

        subgraph Provider["Physics Provider / Systems"]
            Force["Force<br/>Accum."]
            Detection["Collision<br/>Detection"]
            Movement["Movement<br/>Update"]
            Response["Response<br/>Handling"]
        end
    end

    Velocity --> Provider
    Collision --> Provider
    Hitbox --> Provider

Core Components

Velocity Component

Stores entity velocity with server and client versions:

package com.hypixel.hytale.server.core.modules.physics.component;

public class Velocity {
    // Set velocity
    public void set(double x, double y, double z);
    public void set(Vector3d velocity);

    // Add force
    public void addForce(Vector3d force);

    // Get velocity
    public Vector3d getVelocity();
    public Vector3d getClientVelocity();
    public double getSpeed();

    // Instructions for velocity changes
    public void addInstruction(Vector3d velocity, VelocityConfig config,
                               ChangeVelocityType type);
    public List<Instruction> getInstructions();
}

PhysicsValues Component

Physical properties of an entity:

package com.hypixel.hytale.server.core.modules.physics.component;

public class PhysicsValues {
    // Default values
    public static final double DEFAULT_MASS = 1.0;
    public static final double DEFAULT_DRAG_COEFFICIENT = 0.5;
    public static final boolean DEFAULT_INVERTED_GRAVITY = false;

    // Properties
    public double getMass();
    public void setMass(double mass);

    public double getDragCoefficient();
    public void setDragCoefficient(double coefficient);

    public boolean isInvertedGravity();
    public void setInvertedGravity(boolean inverted);
}

BoundingBox Component

Entity collision bounds:

package com.hypixel.hytale.server.core.modules.entity.component;

public class BoundingBox {
    // Main bounding box
    public Box getBoundingBox();
    public void setBoundingBox(Box box);

    // Detail boxes for complex shapes
    public Map<String, DetailBox[]> getDetailBoxes();
    public void setDetailBoxes(Map<String, DetailBox[]> boxes);
}

CollisionModule

Central collision detection system:

package com.hypixel.hytale.server.core.modules.collision;

public class CollisionModule extends JavaPlugin {
    // validation return codes
    public static final int VALIDATE_INVALID = -1;
    public static final int VALIDATE_OK = 0;
    public static final int VALIDATE_ON_GROUND = 1;
    public static final int VALIDATE_TOUCH_CEIL = 2;

    public static CollisionModule get();

    // find collisions along movement path, returns true if far-distance
    public static boolean findCollisions(
        Box collider, Vector3d position, Vector3d velocity,
        CollisionResult result, ComponentAccessor<EntityStore> accessor
    );

    // overload with early-out control
    public static boolean findCollisions(
        Box collider, Vector3d position, Vector3d velocity,
        boolean stopOnCollisionFound,
        CollisionResult result, ComponentAccessor<EntityStore> accessor
    );

    // validate position against block collisions (instance method)
    public int validatePosition(
        World world, Box collider, Vector3d position,
        CollisionResult result
    );

    // block collisions (far distance)
    public static void findBlockCollisionsIterative(
        World world, Box collider, Vector3d pos, Vector3d v,
        boolean stopOnCollisionFound, CollisionResult result
    );

    // block collisions (short distance)
    public static void findBlockCollisionsShortDistance(
        World world, Box collider, Vector3d pos, Vector3d v,
        CollisionResult result
    );

    // entity collisions
    public static void findCharacterCollisions(
        Vector3d pos, Vector3d v, CollisionResult result,
        ComponentAccessor<EntityStore> accessor
    );

    // intersection detection (instance method)
    public void findIntersections(
        World world, Box collider, Vector3d pos,
        CollisionResult result, boolean triggerBlocks, boolean intersections
    );
}

Physics Simulation Flow

1. Force Accumulation

   • External forces, accelerations, impulses collected
   • Gravity applied based on entity properties
   • Fluid forces (buoyancy, drag) calculated

2. Velocity Update

   • Forces integrated to velocity
   • Resistance applied (ground/air)
   • Velocity clamped to limits

3. Movement Computation

   • Delta position calculated from velocity
   • Swept collision detection performed
   • Movement path adjusted for collisions

4. Collision Response

   • Block collisions: bounce, slide, or stop
   • Entity collisions: impact callbacks
   • Trigger blocks: events fired
   • Damage blocks: damage applied

5. State Update

   • Position updated
   • Velocity updated (post-collision)
   • Physics state set (Active/Resting/Inactive)

Physics Constants

// Fluid densities
public static final double DENSITY_AIR = 1.2;
public static final double DENSITY_WATER = 998.0;

// Material masks
public static final int MASK_EMPTY = 1;
public static final int MASK_FLUID = 2;
public static final int MASK_SOLID = 4;
public static final int MASK_SUBMERGED = 8;
public static final int MASK_DAMAGE = 16;

Integration Methods

The physics system supports multiple numerical integration methods:

Method	Class	Accuracy	Performance
Symplectic Euler	PhysicsBodyStateUpdaterSymplecticEuler	Low	Fast
Midpoint	PhysicsBodyStateUpdaterMidpoint	Medium	Medium
Runge-Kutta 4	PhysicsBodyStateUpdaterRK4	High	Slow

Physics States

State	Description
Active	Actively simulating physics
Resting	Stationary on support surface
Inactive	Physics simulation disabled

Entities transition to Resting when velocity is near zero and supported by a block. They wake up when support blocks change.

VelocityConfig

Configures velocity resistance:

package com.hypixel.hytale.server.core.modules.splitvelocity;

public class VelocityConfig {
    float groundResistance = 0.82f;
    float groundResistanceMax;
    float airResistance = 0.96f;
    float airResistanceMax;
    float threshold = 1.0f;
    ThresholdStyle style;  // Linear or non-linear
}

Usage Example

import com.hypixel.hytale.server.core.modules.collision.CollisionModule;
import com.hypixel.hytale.server.core.modules.collision.CollisionResult;
import com.hypixel.hytale.server.core.modules.physics.component.Velocity;
import com.hypixel.hytale.server.core.modules.physics.component.PhysicsValues;
import com.hypixel.hytale.server.core.modules.entity.component.BoundingBox;
import com.hypixel.hytale.math.Box;
import com.hypixel.hytale.math.Vector3d;

public class PhysicsExample {
    public void applyKnockback(Ref<EntityStore> entityRef,
                               IComponentAccessor accessor,
                               Vector3d knockback) {
        // Get velocity component
        Velocity velocity = accessor.getComponent(entityRef, Velocity.getComponentType());

        // Apply knockback force
        velocity.addForce(knockback);
    }

    public boolean checkCollision(World world,
                                  Ref<EntityStore> entityRef,
                                  IComponentAccessor accessor,
                                  Vector3d movement) {
        // Get bounding box
        BoundingBox bbox = accessor.getComponent(entityRef, BoundingBox.getComponentType());
        Box collider = bbox.getBoundingBox();

        // Get current position
        TransformComponent transform = accessor.getComponent(entityRef,
            TransformComponent.getComponentType());
        Vector3d position = transform.getPosition();

        // returns true if far-distance path was used
        CollisionResult result = new CollisionResult();
        boolean isFarDistance = CollisionModule.findCollisions(
            collider, position, movement, result, accessor
        );

        return result.hasBlockCollisions();
    }
}

Related Documentation

• Collision System - Collision detection details
• Hitbox System - Hitbox configuration
• Entity Movement - Velocity and movement
• Entity System - Entity components