nodes/player.py

Part of Squash the Creeps.

"""Player: a CharacterBody3D steered by keys, stick or the drawn pad, with jump and bounce.

Mirrors the upstream Godot player. One typed ``move`` action steers on the XZ
plane, gravity accelerates the body downwards every physics tick, jump adds an
upward impulse, and landing on a creep from above squashes it and bounces the
player back up. Motion goes through ``CharacterBody3D.move_and_slide``, so the
arena's static ground collider is what stops the fall, and creep contact is
found with a masked overlap query rather than a hand-rolled distance test.
"""

from __future__ import annotations

import math

from simvx.core import (
    CharacterBody3D,
    Input,
    Material,
    Mesh,
    MeshInstance3D,
    Node3D,
    Property,
    Quat,
    Signal,
    SphereShape3D,
    Vec3,
)

from .arena import GROUND_Y, LAYER_GROUND, LAYER_MOB, LAYER_PLAYER
from .controls import PLAYER

PLAYER_RADIUS = 0.8
PLAYER_HEIGHT = 1.6

# Metres the player's centre must clear a creep's before a fall counts as a
# stomp rather than a fatal bump.
SQUASH_MIN_HEIGHT = 0.6


class Player(CharacterBody3D):
    """Player character.

    Sits on ``LAYER_PLAYER`` and masks only ``LAYER_GROUND``, so the
    collide-and-slide sweep is blocked by the arena floor and by nothing else:
    creeps are found deliberately, by an overlap query, instead of shoving the
    player around.
    """

    #: The player brings its own controls, so a test that loads the player
    #: alone has them too.
    input_context = PLAYER

    visible = Property(
        False,
        coerce=bool,
        hint="Whether this node and its subtree are drawn",
        on_change="_on_visible_changed",
    )

    speed = Property(14.0, range=(1, 40), hint="Horizontal speed (m/s)")
    jump_impulse = Property(20.0, range=(5, 50), hint="Vertical impulse on jump (m/s)")
    bounce_impulse = Property(16.0, range=(5, 50), hint="Vertical impulse after squashing a mob (m/s)")
    fall_acceleration = Property(75.0, range=(1, 200), hint="Gravity acceleration (m/s^2)")

    hit = Signal()
    squashed_mob = Signal()  # fires when this player lands on a mob

    def __init__(self, **kwargs):
        super().__init__(
            shape=SphereShape3D(radius=PLAYER_RADIUS),
            collision_layer=LAYER_PLAYER,
            collision_mask=LAYER_GROUND,
            **kwargs,
        )
        self.add_to_group("player")
        self._facing_yaw = 0.0
        self._anim_time = 0.0
        self._dead = False

        # Hidden and inert until the root starts a run.
        self.active = False

        # A small pivot we tilt forwards/backwards to mimic the upstream
        # arc-on-jump rotation. Visual mesh is a child of the pivot so the
        # body collider stays axis-aligned.
        self._pivot = self.add_child(Node3D(name="Pivot"))

        # Body: slightly elongated capsule-like cylinder with a head sphere.
        body_mat = Material(colour=(0.95, 0.85, 0.55, 1.0), roughness=0.55, metallic=0.0)
        head_mat = Material(colour=(0.95, 0.85, 0.55, 1.0), roughness=0.45, metallic=0.0)
        eye_mat = Material(colour=(0.05, 0.05, 0.08, 1.0), roughness=0.2, metallic=0.0)

        self._body_mesh = self._pivot.add_child(
            MeshInstance3D(
                name="Body",
                mesh=Mesh.cylinder(radius=PLAYER_RADIUS, height=PLAYER_HEIGHT, segments=20),
                material=body_mat,
                position=Vec3(0, PLAYER_HEIGHT * 0.5, 0),
            )
        )
        self._head_mesh = self._pivot.add_child(
            MeshInstance3D(
                name="Head",
                mesh=Mesh.sphere(radius=PLAYER_RADIUS * 0.85, rings=14, segments=18),
                material=head_mat,
                position=Vec3(0, PLAYER_HEIGHT + PLAYER_RADIUS * 0.4, 0),
            )
        )
        # Eyes: give the player a clear "front" so rotation reads on screen.
        eye_offset = PLAYER_RADIUS * 0.45
        eye_y = PLAYER_HEIGHT + PLAYER_RADIUS * 0.55
        self._pivot.add_child(
            MeshInstance3D(
                name="EyeL",
                mesh=Mesh.sphere(radius=0.12, rings=6, segments=10),
                material=eye_mat,
                position=Vec3(-0.28, eye_y, -eye_offset),
            )
        )
        self._pivot.add_child(
            MeshInstance3D(
                name="EyeR",
                mesh=Mesh.sphere(radius=0.12, rings=6, segments=10),
                material=eye_mat,
                position=Vec3(0.28, eye_y, -eye_offset),
            )
        )

        # Spawn one radius above the arena top so the sphere collider rests on the floor.
        self.position = Vec3(0.0, GROUND_Y + PLAYER_RADIUS, 0.0)
        self.velocity = Vec3()

    # -- run control --------------------------------------------------------

    def start(self) -> None:
        """Reveal the player and begin taking input."""
        self.active = True
        self.visible = True

    def die(self):
        if self._dead:
            return
        self._dead = True
        self.hit.emit()

    @property
    def is_dead(self) -> bool:
        return self._dead

    # -- simulation ---------------------------------------------------------

    def on_fixed_update(self, dt: float):
        if self._dead or not self.active:
            return

        # The camera is a fixed 45-degree isometric rig looking down -Z, so
        # screen right is world +X and screen down is world +Z: the action's
        # vector lands on the ground plane with no unprojection. Keys, a stick
        # and the drawn pad all feed it, and the one furthest from rest wins.
        move = Input.value("move")
        direction = Vec3(move.x, 0.0, move.y)
        if direction.length() > 1e-4:
            direction = direction.normalized()
            self._facing_yaw = math.atan2(direction.x, direction.z)
            self._anim_time += dt * 12.0
        else:
            direction = Vec3()
            self._anim_time += dt * 3.0

        self.velocity.x = direction.x * self.speed
        self.velocity.z = direction.z * self.speed

        # A tick is handed the frame's edges on the frame's first tick, so a
        # press fires once whatever the display and the tick rate are doing.
        if Input.just_pressed("jump") and self.is_on_floor():
            self.velocity.y = self.jump_impulse

        self.velocity.y -= self.fall_acceleration * dt
        self.move_and_slide(dt)

        self._resolve_mob_contacts()
        self._update_visual()

    def _resolve_mob_contacts(self) -> None:
        """Squash a creep landed on from above; any other contact is fatal.

        The overlap query is masked to ``LAYER_MOB``, so neither the player's own
        body nor the arena ground can answer it. Coming down onto a creep from
        clear air squashes it and bounces, in the spirit of upstream's
        ``dot(UP, collision.normal) > 0.1`` test; walking into one ends the run.
        Only the first hit is resolved: a bounce or a death settles the tick.
        """
        query = self.physics
        if query is None:
            return
        hits = query.overlap(self.shape, self.position, mask=LAYER_MOB)
        if not hits:
            return
        mob = hits[0]
        falling_from_above = self.velocity.y < 0.0 and self.position.y - mob.position.y > SQUASH_MIN_HEIGHT
        if not falling_from_above:
            self.die()
            return
        mob.squash()
        self.velocity.y = self.bounce_impulse
        self.squashed_mob.emit()

    def _update_visual(self) -> None:
        """Yaw towards the heading, tilt into the jump arc, bob while grounded."""
        tilt = (math.pi / 6.0) * (self.velocity.y / max(self.jump_impulse, 1e-3))
        self._pivot.rotation = Quat.from_euler(tilt, self._facing_yaw, 0.0)
        bob = math.sin(self._anim_time) * 0.06 if self.is_on_floor() else 0.0
        self._body_mesh.position = Vec3(0, PLAYER_HEIGHT * 0.5 + bob, 0)
        self._head_mesh.position = Vec3(0, PLAYER_HEIGHT + PLAYER_RADIUS * 0.4 + bob, 0)