player

Player entity management and physics controller.

This module defines the Player class, which extends the base Camera to add AABB (Axis-Aligned Bounding Box) collision detection, gravity, fluid dynamics, inventory state, and survival statistics (health, hunger, oxygen). It acts as the primary interface between user input and the 3D voxel world.

class player.Player(app, position=None, yaw=-90.0, pitch=0.0)

Bases: Camera

Represents the player entity in the world.

Handles movement physics, collision detection, block interaction, inventory management, and survival statistics like health and hunger.

Parameters:

• app (Any) – The main application context.

• position (Optional[Any]) – The initial spawn coordinates. If None, it automatically calculates a safe spawn.

• yaw (float) – Initial horizontal rotation in degrees.

• pitch (float) – Initial vertical rotation in degrees.

find_spawn_position()

Locates a valid surface spawn position near the center of the world by scanning outward iteratively until a solid block above water is found.

Return type:

Any

update()

Called every frame. Updates player inputs, physics logic, view bobbing, dynamic FOV for sprinting, fluid dynamics, and core survival metric drains.

Return type:

None

handle_event(event)

Processes discrete user inputs such as key presses (mode toggling, hotbar selection) and mouse clicks (block mining and placing).

Parameters:

event (Any)

Return type:

None

mouse_control()

Retrieves relative mouse movement and adjusts the camera’s yaw and pitch based on the configured sensitivity.

Return type:

None

handle_interaction()

Processes continuous block interactions (mining and placing). Factoring in tool requirements, block hardness, and interaction delays.

Return type:

None

keyboard_control()

Calculates movement vectors based on keyboard input. Adapts movement physics depending on whether the player is in Creative or Survival mode.

Return type:

None

apply_gravity()

Applies downward gravitational acceleration to the player’s vertical velocity, accounting for drag if the player is swimming in water.

Return type:

None

move_and_collide()

Moves the player incrementally along the X, Y, and Z axes, resolving collision clipping individually for each axis.

Return type:

None

resolve_axis(axis)

Checks for intersection between the player’s AABB and the surrounding solid voxels. Stops the player’s velocity along the tested axis if a collision is detected to prevent clipping.

Parameters:

axis (str)

Return type:

None

get_aabb()

Calculates and returns the minimum and maximum boundaries of the Axis-Aligned Bounding Box representing the player’s physical volume.

Return type:

Tuple[Any, Any]

static aabb_intersect(a_min, a_max, b_min, b_max)

Static helper that determines if two given 3D Axis-Aligned Bounding Boxes overlap with each other.

Parameters:

• a_min (Any)

• a_max (Any)

• b_min (Any)

• b_max (Any)

Return type:

bool

add_item(voxel_id)

Attempts to add an item to the player’s inventory by stacking onto existing slots or finding an empty one. Returns True if successful.

Parameters:

voxel_id (int)

Return type:

bool

take_damage(amount)

Reduces player health by the specified amount (if in Survival mode), triggering a respawn sequence if health is completely depleted.

Parameters:

amount (int)

Return type:

None

respawn()

Resets survival statistics and teleports the player back to a safe, auto-calculated spawn position on the surface.

Return type:

None