Files
chameleon/Assets/Scripts/PlayerCharacterController.cs
T
adminandClaude Opus 4.8 fd67936d61 Add wall-climb mantle and wall-relative controls
- Make wall-climb controls wall-relative: W approaches/climbs up,
  S moves away and detaches, A/D strafe along the wall
- Add slow approach speed for moving toward/away from the wall
- Remove wall-climb activation time (activate on contact)
- Add mantle/top-out over the top edge so the player pulls onto the
  surface instead of dropping and re-grabbing (fixes edge flicker)
- Add re-grab cooldown after top-out

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-22 16:39:15 +02:00

550 lines
22 KiB
C#

using UnityEngine;
#if ENABLE_INPUT_SYSTEM
using UnityEngine.InputSystem;
#endif
/// <summary>
/// Simple first/third-person style character controller driven by a
/// <see cref="CharacterController"/>: WASD for horizontal movement and Space to jump.
///
/// Movement can be camera-relative (W moves away from the camera) so it feels
/// natural with the fixed scene camera. Gravity and jumping are integrated
/// manually because CharacterController does not apply physics on its own.
///
/// Touching a wall or ceiling enters a wall-climb mode with
/// wall-relative controls: W moves slowly toward the wall and climbs up once
/// fully against it, S backs slowly away and detaches once far enough, and A/D
/// strafe left/right along the wall. Gravity and jumping are ignored while
/// climbing. Climbing up past the top edge mantles the character over onto the
/// surface instead of dropping back down.
///
/// The script reads input through the new Input System (Keyboard.current) when it
/// is enabled, and falls back to the legacy Input Manager otherwise. The project
/// currently runs the new Input System only.
///
/// Attach this to the Player GameObject (the one that owns the CharacterController).
///
/// Note: the class is intentionally named PlayerCharacterController to avoid a
/// name clash with Unity.VisualScripting's example "PlayerController" type.
/// </summary>
[RequireComponent(typeof(CharacterController))]
[DisallowMultipleComponent]
public class PlayerCharacterController : MonoBehaviour
{
[Header("Movement")]
[Tooltip("Horizontal movement speed in units per second.")]
public float moveSpeed = 4f;
[Tooltip("If ON, WASD is interpreted relative to the camera (W = away from " +
"the camera). If OFF, WASD moves along the world X/Z axes.")]
public bool cameraRelative = true;
[Tooltip("Camera used for camera-relative movement. Empty = Camera.main.")]
public Transform cameraTransform;
[Header("Rotation")]
[Tooltip("If ON, the character smoothly turns to face its movement direction.")]
public bool rotateTowardMovement = true;
[Tooltip("Turn speed in degrees per second (used when 'Rotate Toward Movement' is on).")]
public float rotationSpeed = 720f;
[Header("Jump & Gravity")]
[Tooltip("Peak jump height in units.")]
public float jumpHeight = 1.2f;
[Tooltip("Gravity in units per second squared (negative = downward).")]
public float gravity = -19.62f;
[Tooltip("Small downward velocity kept while grounded so the controller " +
"stays firmly on the ground (and isGrounded stays reliable).")]
public float groundedStickVelocity = -2f;
[Header("Slope Sliding")]
[Tooltip("If ON, the character slides down surfaces steeper than the " +
"CharacterController's Slope Limit (and off sharp edges/corners) " +
"instead of balancing on them.")]
public bool slideDownSteepSlopes = true;
[Tooltip("How quickly the slide accelerates while on a too-steep surface " +
"(units per second squared).")]
public float slideAcceleration = 20f;
[Tooltip("Maximum downhill slide speed (units per second).")]
public float maxSlideSpeed = 8f;
[Tooltip("How much steering control the player keeps while sliding " +
"(0 = none, 1 = full normal control).")]
[Range(0f, 1f)]
public float slideControl = 0.3f;
[Header("Wall Climb")]
[Tooltip("If ON, the character enters a wall-climb mode after touching a " +
"wall or ceiling for a short time: it sticks to the surface, moves " +
"at reduced speed and ignores gravity and jumping until contact is lost.")]
public bool enableWallClimb = true;
[Tooltip("Minimum surface angle from 'up' (in degrees) for a contact to " +
"count as a climbable wall or ceiling. Surfaces between the slope " +
"limit and this angle stay (sliding) slopes; at or above this they " +
"are treated as walls/ceilings.")]
[Range(50f, 180f)]
public float wallMinAngle = 80f;
[Tooltip("Speed multiplier for climbing up (W when against the wall) and " +
"strafing left/right (A/D) while wall-climbing (0.5 = half speed).")]
[Range(0f, 1f)]
public float wallClimbSpeedMultiplier = 0.5f;
[Tooltip("Speed (units per second) for moving toward (W) or away from (S) the " +
"wall while climbing. Deliberately slow so approaching/detaching is gentle.")]
public float wallApproachSpeed = 0.5f;
[Tooltip("Gap (in units) below which the character counts as fully against " +
"the wall, so pressing forward (W) climbs up instead of moving closer.")]
public float wallContactDistance = 0.05f;
[Tooltip("Gap (in units) from the wall at which holding back (S) leaves " +
"wall-climb mode.")]
public float wallDetachDistance = 0.25f;
[Tooltip("Grace period (seconds) of lost contact tolerated before leaving " +
"wall-climb mode (prevents flicker on bumpy geometry/edges).")]
public float wallExitGrace = 0.15f;
/// <summary>
/// When false, movement/jump input is ignored (the player stands still), but
/// gravity and ground contact keep running so the character stays grounded.
/// Toggled by the GameModeManager (e.g. disabled in paint mode).
/// </summary>
public bool ControlEnabled { get; set; } = true;
/// <summary>True while the character is in wall-climb mode (stuck to a wall/ceiling).</summary>
public bool IsWallClimbing => _isWallClimbing;
private CharacterController _controller;
private float _verticalVelocity;
// Ground contact normal collected from the latest Move (used for slope sliding).
private Vector3 _groundNormal = Vector3.up;
private bool _groundNormalUpdated;
private float _slideSpeed;
// Wall-climb state.
private bool _isWallClimbing;
private Vector3 _wallNormal; // surface normal of the climbed wall/ceiling
private Vector3 _wallNormalAccum; // summed wall normals during the latest Move
private bool _wallContactThisFrame; // any wall/ceiling touched during the latest Move
private float _lostContactTimer; // continuous lost-contact time while climbing
private readonly RaycastHit[] _wallProbe = new RaycastHit[8]; // buffer for the wall-distance probe
// Mantle (top-out) state: climbing up past the wall's top edge pulls the
// character up and over onto the surface instead of dropping back down.
private bool _mantling; // a mantle is currently in progress
private bool _mantleClearedFeet; // phase 1 done: whole capsule is above the edge
private float _mantleOverDist; // phase 2 forward distance moved over the top
private float _mantleTimer; // safety cap so a mantle can never run forever
private float _reentryCooldown; // blocks re-grabbing the wall right after topping out
void Awake()
{
_controller = GetComponent<CharacterController>();
if (cameraTransform == null && Camera.main != null)
cameraTransform = Camera.main.transform;
}
void Update()
{
// --- Read input -----------------------------------------------------
float h = 0f, v = 0f;
bool jumpPressed = false;
// Skip input entirely when control is disabled (e.g. paint mode); gravity
// and grounding below still run so the player stays planted on the ground.
if (ControlEnabled)
{
#if ENABLE_INPUT_SYSTEM
var keyboard = Keyboard.current;
if (keyboard != null)
{
if (keyboard.aKey.isPressed) h -= 1f;
if (keyboard.dKey.isPressed) h += 1f;
if (keyboard.sKey.isPressed) v -= 1f;
if (keyboard.wKey.isPressed) v += 1f;
jumpPressed = keyboard.spaceKey.wasPressedThisFrame;
}
#else
h = Input.GetAxisRaw("Horizontal");
v = Input.GetAxisRaw("Vertical");
jumpPressed = Input.GetButtonDown("Jump");
#endif
}
// --- Build the horizontal move direction ----------------------------
Vector3 inputDir = new Vector3(h, 0f, v);
if (inputDir.sqrMagnitude > 1f)
inputDir.Normalize();
Vector3 moveDir;
if (cameraRelative && cameraTransform != null)
{
// Project the camera axes onto the ground plane so movement stays horizontal.
Vector3 forward = cameraTransform.forward;
forward.y = 0f;
forward.Normalize();
Vector3 right = cameraTransform.right;
right.y = 0f;
right.Normalize();
moveDir = forward * inputDir.z + right * inputDir.x;
}
else
{
moveDir = inputDir;
}
// --- Wall-climb state machine ---------------------------------------
// Evaluates the wall/ceiling contact gathered during the previous Move,
// then enters/leaves wall-climb mode accordingly.
UpdateWallClimbState();
// Latch the wall normal for this frame's movement, then reset the
// per-frame contact accumulators (OnControllerColliderHit refills them
// during the Move calls below / above).
if (_wallContactThisFrame && _wallNormalAccum.sqrMagnitude > 1e-6f)
_wallNormal = _wallNormalAccum.normalized;
_wallContactThisFrame = false;
_wallNormalAccum = Vector3.zero;
if (_isWallClimbing)
{
// While climbing: wall-relative WASD, no gravity, no jump, no slope
// sliding, no forced alignment. Done for this frame.
ApplyWallClimbMovement(h, v, Time.deltaTime);
return;
}
// --- Evaluate the ground slope (for sliding) ------------------------
// The ground normal is gathered in OnControllerColliderHit during the
// previous Move. If it is steeper than the controller's Slope Limit, the
// surface is too steep to stand on (this also covers balancing on a sharp
// box edge/corner, whose contact normal is steep).
float slopeAngle = Vector3.Angle(_groundNormal, Vector3.up);
bool onSteepSlope = slideDownSteepSlopes
&& _controller.isGrounded
&& slopeAngle > _controller.slopeLimit + 0.01f;
// --- Gravity & jumping ---------------------------------------------
if (_controller.isGrounded)
{
// Reset accumulated fall speed and keep a small downward bias on the ground.
if (_verticalVelocity < 0f)
_verticalVelocity = groundedStickVelocity;
// No jumping off a slope that is too steep to stand on.
if (jumpPressed && !onSteepSlope)
_verticalVelocity = Mathf.Sqrt(jumpHeight * -2f * gravity);
}
_verticalVelocity += gravity * Time.deltaTime;
// --- Slope sliding --------------------------------------------------
Vector3 slideVelocity = Vector3.zero;
if (onSteepSlope)
{
// Steepest-descent direction along the slope surface.
Vector3 slideDir = Vector3.ProjectOnPlane(Vector3.down, _groundNormal).normalized;
// Accelerate the slide up to the maximum slide speed.
_slideSpeed = Mathf.Min(_slideSpeed + slideAcceleration * Time.deltaTime, maxSlideSpeed);
slideVelocity = slideDir * _slideSpeed;
// While sliding the player keeps only reduced steering control.
moveDir *= slideControl;
}
else
{
_slideSpeed = 0f;
}
// --- Apply movement -------------------------------------------------
Vector3 velocity = moveDir * moveSpeed + slideVelocity + Vector3.up * _verticalVelocity;
// Reset the per-frame ground-normal collection, then Move (which fires
// OnControllerColliderHit), then fall back to "up" if nothing was hit.
_groundNormalUpdated = false;
_controller.Move(velocity * Time.deltaTime);
if (!_groundNormalUpdated)
_groundNormal = Vector3.up;
// --- Rotate toward the movement direction ---------------------------
if (rotateTowardMovement && moveDir.sqrMagnitude > 0.0001f)
{
Quaternion target = Quaternion.LookRotation(moveDir, Vector3.up);
transform.rotation = Quaternion.RotateTowards(
transform.rotation, target, rotationSpeed * Time.deltaTime);
}
}
/// <summary>
/// Drives entry into wall-climb mode: any wall/ceiling contact enters the mode
/// immediately (or bails out when the feature/control is disabled). Leaving the
/// mode while climbing is handled in <see cref="ApplyWallClimbMovement"/>
/// (raycast-based).
/// </summary>
private void UpdateWallClimbState()
{
// Cool down the post-mantle re-grab lock (runs whether climbing or not).
if (_reentryCooldown > 0f)
_reentryCooldown -= Time.deltaTime;
if (!enableWallClimb || !ControlEnabled)
{
if (_isWallClimbing)
ExitWallClimb();
return;
}
if (!_isWallClimbing && _wallContactThisFrame && _reentryCooldown <= 0f)
{
// Any wall/ceiling contact enters wall-climb mode immediately. The
// cooldown above prevents instantly re-grabbing the edge we just
// mantled over (which would otherwise cause a climb/drop flicker).
_isWallClimbing = true;
_lostContactTimer = 0f;
_verticalVelocity = 0f;
_slideSpeed = 0f;
}
// While climbing, exit is decided in ApplyWallClimbMovement (intentional
// back-off with S, or losing the wall after the grace period).
}
/// <summary>
/// Moves the character along the climbed surface using wall-relative WASD:
/// W moves slowly toward the wall and, once fully against it, climbs up;
/// S moves slowly away and detaches once far enough; A/D strafe left/right
/// along the wall. The current wall normal and gap are measured each frame by
/// a raycast toward the surface. No gravity, no jump, no forced alignment.
/// </summary>
private void ApplyWallClimbMovement(float h, float v, float dt)
{
// A mantle (top-out) overrides normal climbing until it finishes.
if (_mantling)
{
MantleOverEdge(dt);
return;
}
// Probe the wall ahead to refresh its normal and our distance to it.
bool found = ProbeWall(out Vector3 probedNormal, out float gap);
if (found)
{
_wallNormal = probedNormal;
_lostContactTimer = 0f;
}
else
{
// The body-center ray lost the wall. If we were climbing up (W) and the
// wall still exists down at the feet, we have reached the top edge:
// mantle up and over onto the surface instead of dropping.
if (v > 0f && WallInFront(_controller.height * 0.5f))
{
_mantling = true;
_mantleClearedFeet = false;
_mantleOverDist = 0f;
_mantleTimer = 0f;
MantleOverEdge(dt);
return;
}
// Otherwise the wall is genuinely gone: leave after the grace period.
_lostContactTimer += dt;
gap = wallDetachDistance + 1f; // treat as "far" so it cannot block exit
if (_lostContactTimer >= wallExitGrace)
{
ExitWallClimb();
return;
}
}
// Build a basis on the wall plane: "up along the wall" and "right".
Vector3 climbUp = Vector3.ProjectOnPlane(Vector3.up, _wallNormal);
if (climbUp.sqrMagnitude < 1e-6f) // degenerate on a flat ceiling: fall back to facing
climbUp = Vector3.ProjectOnPlane(transform.forward, _wallNormal);
climbUp.Normalize();
Vector3 right = Vector3.Cross(_wallNormal, climbUp).normalized;
float climbSpeed = moveSpeed * wallClimbSpeedMultiplier;
// A/D always strafe left/right along the wall.
Vector3 velocity = right * (h * climbSpeed);
bool detach = false;
if (v > 0f)
{
// W: move closer to the wall while there is a gap, otherwise climb up.
if (gap > wallContactDistance)
velocity += -_wallNormal * (v * wallApproachSpeed); // slow approach
else
velocity += climbUp * (v * climbSpeed); // climb up
}
else if (v < 0f)
{
// S: slowly back away from the wall; detach once far enough.
velocity += -_wallNormal * (v * wallApproachSpeed); // v < 0 => away from wall
if (gap >= wallDetachDistance)
detach = true;
}
_controller.Move(velocity * dt);
if (detach)
ExitWallClimb();
}
/// <summary>
/// Casts a ray from the character center toward the wall (opposite the wall
/// normal) to find the current surface normal and the gap between the
/// controller's side and the wall. The player's own colliders (controller and
/// the paintable mesh collider) are skipped. Returns false if no wall is found
/// within reach.
/// </summary>
private bool ProbeWall(out Vector3 normal, out float gap)
{
normal = _wallNormal;
gap = 0f;
Vector3 origin = transform.position + _controller.center;
float radius = _controller.radius;
float maxDist = radius + wallDetachDistance + 0.5f;
int count = Physics.RaycastNonAlloc(
origin, -_wallNormal, _wallProbe, maxDist, ~0, QueryTriggerInteraction.Ignore);
float best = float.MaxValue;
bool found = false;
for (int i = 0; i < count; i++)
{
// Skip our own hierarchy (the CharacterController and the child mesh collider).
if (_wallProbe[i].collider.transform.IsChildOf(transform))
continue;
if (_wallProbe[i].distance < best)
{
best = _wallProbe[i].distance;
normal = _wallProbe[i].normal;
found = true;
}
}
if (found)
gap = Mathf.Max(0f, best - radius);
return found;
}
/// <summary>
/// Pulls the character up and over the wall's top edge onto the surface.
/// Phase 1 rises along the wall face until the whole capsule is above the
/// edge; phase 2 moves forward over the top, after which wall-climb is left
/// and gravity settles the character onto the surface. A short re-grab
/// cooldown is armed so the freshly passed edge does not re-trigger a climb.
/// </summary>
private void MantleOverEdge(float dt)
{
_mantleTimer += dt;
float speed = moveSpeed * wallClimbSpeedMultiplier;
// Forward direction over the edge: horizontal, opposite the wall normal.
Vector3 forward = -_wallNormal;
forward.y = 0f;
forward = forward.sqrMagnitude > 1e-6f ? forward.normalized : transform.forward;
if (!_mantleClearedFeet)
{
// Phase 1: climb straight up until no wall is left in front of the feet.
_controller.Move(Vector3.up * (speed * dt));
if (!WallInFront(_controller.height * 0.5f))
_mantleClearedFeet = true;
}
else
{
// Phase 2: move forward onto the top surface, then finish.
_controller.Move(forward * (speed * dt));
_mantleOverDist += speed * dt;
if (_mantleOverDist >= _controller.radius * 2f + 0.15f || _controller.isGrounded)
{
_reentryCooldown = 0.3f;
ExitWallClimb();
return;
}
}
// Safety: never mantle indefinitely (e.g. if blocked by other geometry).
if (_mantleTimer >= 2f)
{
_reentryCooldown = 0.3f;
ExitWallClimb();
}
}
/// <summary>
/// Casts a horizontal ray toward the wall from a point <paramref name="downOffset"/>
/// below the controller center, ignoring our own colliders. Used to tell a top
/// edge (wall still present lower down) from the wall being truly gone.
/// </summary>
private bool WallInFront(float downOffset)
{
Vector3 origin = transform.position + _controller.center - Vector3.up * downOffset;
float maxDist = _controller.radius + wallDetachDistance + 0.5f;
int count = Physics.RaycastNonAlloc(
origin, -_wallNormal, _wallProbe, maxDist, ~0, QueryTriggerInteraction.Ignore);
for (int i = 0; i < count; i++)
{
if (_wallProbe[i].collider.transform.IsChildOf(transform))
continue;
return true;
}
return false;
}
/// <summary>Leaves wall-climb mode and resets vertical velocity so the player falls cleanly.</summary>
private void ExitWallClimb()
{
_isWallClimbing = false;
_lostContactTimer = 0f;
_verticalVelocity = 0f;
_mantling = false;
_mantleClearedFeet = false;
_mantleOverDist = 0f;
_mantleTimer = 0f;
}
/// <summary>
/// Collects contact normals during <see cref="CharacterController.Move"/>.
/// Wall/ceiling contacts (angle at or above <see cref="wallMinAngle"/>) feed
/// the wall-climb detector; among the upward-facing contacts the flattest one
/// is kept as the ground normal the character is actually standing on.
/// </summary>
private void OnControllerColliderHit(ControllerColliderHit hit)
{
// Detect walls/ceilings for wall-climbing (steep enough to not be a slope).
if (enableWallClimb)
{
float angle = Vector3.Angle(hit.normal, Vector3.up);
if (angle >= wallMinAngle)
{
_wallContactThisFrame = true;
_wallNormalAccum += hit.normal;
}
}
// Ignore near-vertical walls and ceilings for ground-normal collection.
if (hit.normal.y <= 0.05f)
return;
// Keep the flattest (most supportive) contact seen this frame.
if (!_groundNormalUpdated || hit.normal.y > _groundNormal.y)
{
_groundNormal = hit.normal;
_groundNormalUpdated = true;
}
}
}