namespace ShrimpleCharacterController; [Icon("nordic_walking")] public class ShrimpleCharacterController : Component { /// /// Manually update this by calling Move() or let it always be simulated /// [Property] [Group("Options")] public bool ManuallyUpdate { get; set; } = true; /// /// If pushing against a wall, scale the velocity based on the wall's angle (False is useful for NPCs that get stuck on corners) /// [Property] [Group("Options")] public bool ScaleAgainstWalls { get; set; } = true; [Sync] float _traceWidth { get; set; } = 16f; /// /// Width of our trace /// [Property] [Group("Trace")] [Range(1f, 64f, 1f, true, true)] public float TraceWidth { get => _traceWidth; set { _traceWidth = value; Bounds = BuildBounds(); _shrunkenBounds = Bounds.Grow(-SkinWidth); } } [Sync] float _traceHeight { get; set; } = 72f; /// /// Height of our trace /// [Property] [Group("Trace")] [Range(1f, 256f, 1f, true, true)] public float TraceHeight { get => _traceHeight; set { _traceHeight = value; Bounds = BuildBounds(); _shrunkenBounds = Bounds.Grow(-SkinWidth); } } /// /// Which tags it should ignore /// [Property] [Group("Trace")] public TagSet IgnoreTags { get; set; } = new TagSet(); /// /// Max amount of trace calls whenever the simulation doesn't reach its target (Slide and collide bounces) /// [Property] [Group("Trace")] [Range(1, 20, 1, true, true)] public int MaxBounces { get; set; } = 5; /// /// How fast you accelerate while on the ground (Units per second) /// [Property] [Group("Movement")] [Range(0f, 3000f, 10f, false)] [HideIf("GroundStickEnabled", false)] public float GroundAcceleration { get; set; } = 1000f; /// /// How fast you decelerate while on the ground (Units per second) /// [Property] [Group("Movement")] [Range(0f, 3000f, 10f, false)] [HideIf("GroundStickEnabled", false)] public float GroundDeceleration { get; set; } = 1500f; /// /// How fast you accelerate while in the air (Units per second) /// [Property] [Group("Movement")] [Range(0f, 3000f, 10f, false)] public float AirAcceleration { get; set; } = 300f; /// /// How fast you decelerate while in the air (Units per second) /// [Property] [Group("Movement")] [Range(0f, 3000f, 10f, false)] public float AirDeceleration { get; set; } = 0f; /// /// Do we ignore the friction of the surface you're standing on or not? /// [Property] [Group("Movement")] public bool IgnoreGroundSurface { get; set; } = false; /// /// Is this MoveHelper meant for horizontal grounded movement? (false = For flying or noclip) /// [Property] [Group("Movement")] public bool IgnoreZ { get; set; } = true; /// /// Do we ignore Z when it's near 0 (So that gravity affects you when not moving) /// [Property] [Title("Ignore Z When Zero")] [Group("Movement")] [HideIf("IgnoreZ", true)] public bool IgnoreZWhenZero { get; set; } = true; /// /// Tolerance from a 90° surface before it's considered a wall (Ex. Tolerance 1 = Between 89° and 91° can be a wall, 0.1 = 89.9° to 90.1°) /// [Group("Movement")] [Property] [Range(0f, 10f, 0.1f, false)] public float WallTolerance { get; set; } = 1f; /// /// Player feels like it's gripping walls too much? Try more Grip Factor Reduction! /// [Group("Movement")] [Property] [Range(1f, 10f, 0.1f, true)] public float GripFactorReduction { get; set; } = 1f; /// /// Stick the MoveHelper to the ground (IsOnGround will default to false if disabled) /// [ToggleGroup("GroundStickEnabled")] [Property] public bool GroundStickEnabled { get; set; } = true; /// /// How steep terrain can be for you to stand on without slipping /// [Property] [Group("GroundStickEnabled")] [Range(0f, 89f, 1f, true, true)] public float MaxGroundAngle { get; set; } = 60f; /// /// How far from the ground the MoveHelper is going to stick (Useful for going down stairs!) /// [Property] [Group("GroundStickEnabled")] [Range(1f, 32f, 1f, false)] public float GroundStickDistance { get; set; } = 12f; /// /// Enable steps climbing (+1 Trace call) /// [ToggleGroup("StepsEnabled")] [Property] public bool StepsEnabled { get; set; } = true; /// /// How high steps can be for you to climb on /// [Group("StepsEnabled")] [Property] [Range(1f, 32f, 1f, false)] public float StepHeight { get; set; } = 12f; /// /// How deep it checks for steps (Minimum depth) /// [Group("StepsEnabled")] [Property] [Range(0.1f, 8f, 0.1f, false)] public float StepDepth { get; set; } = 2f; /// /// Tolerance from a 90° surface before it's considered a valid step (Ex. Tolerance 1 = Between 89° and 91° can be a step, 0.1 = 89.9° to 90.1°) /// [Group("StepsEnabled")] [Property] [Range(0f, 10f, 0.1f, false)] public float StepTolerance { get; set; } = 1f; /// /// Enable to ability to walk on a surface that's too steep if it's equal or smaller than a step (+1 Trace call when on steep terrain) /// [Group("StepsEnabled")] [Property] public bool PseudoStepsEnabled { get; set; } = true; /// /// Instead of colliding with these tags the MoveHelper will be pushed away (Make sure the tags are in IgnoreTags as well!) /// [ToggleGroup("PushEnabled")] [Property] public bool PushEnabled { get; set; } = false; [Sync] Dictionary _pushTagsWeight { get; set; } = new Dictionary() { { "player", 1f } }; /// /// Which tags will push this MoveHelper away and with how much force (Make sure they are also included in IgnoreTags!) (+1 Trace call) /// [Property] [Group("PushEnabled")] public Dictionary PushTagsWeight { get => _pushTagsWeight; set { _pushTagsWeight = value; _pushTags = BuildPushTags(); } } /// /// Apply gravity to this MoveHelper when not on the ground /// [ToggleGroup("GravityEnabled")] [Property] public bool GravityEnabled { get; set; } = true; /// /// Use the scene's gravity or our own /// [Property] [Group("GravityEnabled")] public bool UseSceneGravity { get; set; } = true; /// /// Units per second squared (Default is -850f) /// [Property] [Group("GravityEnabled")] [Range(-2000, 2000, 1, false)] [HideIf("UseSceneGravity", true)] public float Gravity { get; set; } = -850f; /// /// Check if the MoveHelper is stuck and try to get it to unstuck (+Trace calls if stuck) /// [ToggleGroup("UnstuckEnabled")] [Property] public bool UnstuckEnabled { get; set; } = true; /// /// How many trace calls it will attempt to get the MoveHelper unstuck /// [Property] [Group("UnstuckEnabled")] [Range(1, 50, 1, false)] public int MaxUnstuckTries { get; set; } = 20; /// /// The simulated target velocity for our MoveHelper (Units per second, we apply Time.Delta inside) /// [Sync] public Vector3 WishVelocity { get; set; } /// /// The resulting velocity after the simulation is done (Units per second) /// [Sync] public Vector3 Velocity { get; set; } /// /// Is the MoveHelper currently touching the ground /// [Sync] public bool IsOnGround { get; set; } /// The current ground normal you're standing on (Always Vector3.Zero if IsOnGround false) /// public Vector3 GroundNormal { get; private set; } = Vector3.Zero; /// /// The current ground angle you're standing on (Always 0f if IsOnGround false) /// public float GroundAngle => Vector3.GetAngle(GroundNormal, Vector3.Up); /// /// The current surface you're standing on /// public Surface GroundSurface { get; private set; } /// /// The gameobject you're currently standing on /// public GameObject GroundObject { get; set; } /// /// Is the MoveHelper currently pushing against a wall /// public bool IsPushingAgainstWall { get; private set; } /// /// The current wall normal you're pushing against (Always Vector3.Zero if IsPushingAgainstWall false) /// public Vector3 WallNormal { get; private set; } = Vector3.Zero; /// /// The gameobject you're currently pushing on /// public GameObject WallObject { get; set; } /// /// Is the MoveHelper standing on a terrain too steep to stand on (Always false if IsOnGround false) /// [Sync] public bool IsSlipping { get; private set; } // TODO IMPLEMENT /// /// The MoveHelper is stuck and we can't get it out /// [Sync] public bool IsStuck { get; private set; } /// /// To avoid getting stuck due to imprecision we shrink the bounds before checking and compensate for it later /// public float SkinWidth; /// /// The bounds of this MoveHelper generated from the TraceWidth and TraceHeight /// public BBox Bounds { get; set; } private BBox _shrunkenBounds; private string[] _pushTags; private Vector3 _lastVelocity; /// /// If another MoveHelper moved at the same time and they're stuck, let this one know that the other already unstuck for us /// public ShrimpleCharacterController UnstuckTarget; protected override void OnStart() { SkinWidth = Math.Min(Math.Max(0.1f, TraceWidth * 0.05f), GroundStickDistance); // SkinWidth is 5% of the total width Bounds = BuildBounds(); _shrunkenBounds = Bounds.Grow(-SkinWidth); _pushTags = BuildPushTags(); } protected override void DrawGizmos() { if (Gizmo.IsSelected) { Gizmo.GizmoDraw draw = Gizmo.Draw; draw.Color = Color.Blue; draw.LineBBox(BuildBounds()); } } private BBox BuildBounds() { return new BBox(new Vector3(-TraceWidth / 2, -TraceWidth / 2f, 0f), new Vector3(TraceWidth / 2f, TraceWidth / 2f, TraceHeight)); } private string[] BuildPushTags() { return PushTagsWeight.Keys.ToArray(); } /// /// Casts the current bounds from to and returns the scene trace result /// /// /// /// /// public SceneTraceResult BuildTrace(BBox bounds, Vector3 from, Vector3 to) { return Game.SceneTrace.Box(bounds, from, to) .IgnoreGameObjectHierarchy(GameObject) .WithoutTags(IgnoreTags) .Run(); } private SceneTraceResult BuildPushTrace(BBox bounds, Vector3 from, Vector3 to) { return Game.SceneTrace.Box(bounds, from, to) .IgnoreGameObjectHierarchy(GameObject) .WithAnyTags(_pushTags) // Check for only the push tags .Run(); } /// /// Detach the MoveHelper from the ground and launch it somewhere (Units per second) /// /// public void Punch(in Vector3 amount) { if (amount.z < 10f) return; // Get out with that weak crap IsOnGround = false; Velocity += amount; } /// /// Apply the WishVelocity, update the Velocity and the Position of the GameObject by simulating the MoveHelper /// /// Just calculate but don't update position public MoveHelperResult Move(bool manualUpdate = false) => Move(Time.Delta, manualUpdate); /// /// Apply the WishVelocity, update the Velocity and the Position of the GameObject by simulating the MoveHelper /// /// The time step /// Just calculate but don't update position public MoveHelperResult Move(float delta, bool manualUpdate = false) { var goalVelocity = CalculateGoalVelocity(delta); // Calculate the goal velocity using our Acceleration and Deceleration values // KNOWN ISSUE: Velocity starts to build up to massive amounts when trying to climb terrain too steep? // SIMULATE PUSH FORCES // if (PushEnabled) { var pushTrace = BuildPushTrace(Bounds, WorldPosition, WorldPosition); // Build a trace but using the Push tags instead of the Ignore tags if (pushTrace.Hit) // We're inside any of the push tags { foreach (var tag in pushTrace.GameObject.Tags) { if (PushTagsWeight.TryGetValue(tag, out var tagWeight)) { var otherPosition = pushTrace.GameObject.WorldPosition.WithZ(WorldPosition.z); // Only horizontal pushing var pushDirection = (otherPosition - WorldPosition).Normal; var pushVelocity = pushDirection * tagWeight * 50f; // I find 50 u/s to be a good amount to push if the weight is 1.0 (!!!) goalVelocity -= pushVelocity; } } } } var moveHelperResult = CollideAndSlide(goalVelocity, WorldPosition, delta); // Simulate the MoveHelper var finalPosition = moveHelperResult.Position; var finalVelocity = moveHelperResult.Velocity; // SIMULATE GRAVITY // if (GravityEnabled && Gravity != 0f) { if (!IsOnGround || IsSlipping || !GroundStickEnabled) { var gravityAmount = UseSceneGravity ? Scene.PhysicsWorld.Gravity.z : Gravity; var gravity = gravityAmount * Vector3.Up * delta; var gravityResult = CollideAndSlide(gravity, moveHelperResult.Position, delta, gravityPass: true); // Apply and simulate the gravity step finalPosition = gravityResult.Position; finalVelocity += gravityResult.Velocity; } } _lastVelocity = Velocity * delta; if (!manualUpdate) { Velocity = finalVelocity; WorldPosition = finalPosition; // Actually updating the position is "expensive" so we only do it once at the end } return new MoveHelperResult(finalPosition, finalVelocity); } /// /// Sometimes we have to update only the position but not the velocity (Like when climbing steps or getting unstuck) so we can't have Position rely only on Velocity /// public struct MoveHelperResult { public Vector3 Position; public Vector3 Velocity; public MoveHelperResult(Vector3 position, Vector3 velocity) { Position = position; Velocity = velocity; } } private MoveHelperResult CollideAndSlide(Vector3 velocity, Vector3 position, float delta, int depth = 0, bool gravityPass = false) => CollideAndSlide(new MoveHelperResult(position, velocity), delta, depth, gravityPass); private MoveHelperResult CollideAndSlide(MoveHelperResult current, float delta, int depth = 0, bool gravityPass = false) { if (depth >= MaxBounces) return current; var velocity = current.Velocity * delta; // I like to set Velocity as units/second but we have to deal with units/tick here var position = current.Position; // GROUND AND UNSTUCK CHECK // if (depth == 0) // Only check for the first step since it's impossible to get stuck on other steps { var groundTrace = BuildTrace(_shrunkenBounds, position, position + Vector3.Down * GroundStickDistance); if (groundTrace.StartedSolid) { IsStuck = true; if (UnstuckEnabled) { if (UnstuckTarget == null) { IsStuck = !TryUnstuck(position, out var result); if (!IsStuck) { position = result; // Update the new position if (groundTrace.GameObject != null) if (groundTrace.GameObject.Components.TryGet(out var otherHelper)) otherHelper.UnstuckTarget = this; // We already solved this, no need to unstuck the other helper } else { return new MoveHelperResult(position, Vector3.Zero); // Mission failed, bail out! } } else { UnstuckTarget = null; // Alright the other MoveHelper got us unstuck so just do nothing } } } else { var hasLanded = !IsOnGround && Velocity.z <= 0f && groundTrace.Hit && groundTrace.Distance <= SkinWidth * 2f; // Wasn't on the ground and now is var isGrounded = IsOnGround && groundTrace.Hit; // Was already on the ground and still is, this helps stick when going down stairs IsOnGround = hasLanded || isGrounded; GroundSurface = IsOnGround ? groundTrace.Surface : null; GroundNormal = IsOnGround ? groundTrace.Normal : Vector3.Up; GroundObject = IsOnGround ? groundTrace.GameObject : null; IsSlipping = IsOnGround && GroundAngle > MaxGroundAngle; if (IsSlipping && !gravityPass && velocity.z > 0f) velocity = velocity.WithZ(0f); // If we're slipping ignore any extra velocity we had if (IsOnGround && GroundStickEnabled && !IsSlipping) { position = groundTrace.EndPosition + Vector3.Up * SkinWidth; // Place on the ground velocity = Vector3.VectorPlaneProject(velocity, GroundNormal); // Follow the ground you're on without projecting Z } IsStuck = false; } } if (velocity.IsNearlyZero(0.01f)) // Not worth continuing, reduces small stutter { return new MoveHelperResult(position, Vector3.Zero); } var toTravel = velocity.Length + SkinWidth; var targetPosition = position + velocity.Normal * toTravel; var travelTrace = BuildTrace(_shrunkenBounds, position, targetPosition); if (travelTrace.Hit) { var travelled = velocity.Normal * Math.Max(travelTrace.Distance - SkinWidth, 0f); var leftover = velocity - travelled; // How much leftover velocity still needs to be simulated var angle = Vector3.GetAngle(Vector3.Up, travelTrace.Normal); if (toTravel >= SkinWidth && travelTrace.Distance < SkinWidth) travelled = Vector3.Zero; if (angle <= MaxGroundAngle) // Terrain we can walk on { if (gravityPass || !IsOnGround) leftover = Vector3.VectorPlaneProject(leftover, travelTrace.Normal); // Don't project the vertical velocity after landing else it boosts your horizontal velocity else leftover = leftover.ProjectAndScale(travelTrace.Normal); // Project the velocity along the terrain IsPushingAgainstWall = false; WallObject = null; } else { var climbedStair = false; if (angle >= 90f - WallTolerance && angle <= 90f + WallTolerance) // Check for walls IsPushingAgainstWall = true; // We're pushing against a wall if (StepsEnabled) { var isStep = angle >= 90f - StepTolerance && angle <= 90f + StepTolerance; if (isStep || PseudoStepsEnabled) // Check for steps { if (IsOnGround) // Stairs VVV { var stepHorizontal = velocity.WithZ(0f).Normal * StepDepth; // How far in front we're looking for steps var stepVertical = Vector3.Up * StepHeight; // How high we're looking for steps var stepTrace = BuildTrace(_shrunkenBounds, travelTrace.EndPosition + stepHorizontal + stepVertical, travelTrace.EndPosition + stepHorizontal); var stepAngle = Vector3.GetAngle(stepTrace.Normal, Vector3.Up); if (!stepTrace.StartedSolid && stepTrace.Hit && stepAngle <= MaxGroundAngle) // We found a step! { if (isStep || !IsSlipping && PseudoStepsEnabled) { var stepDistance = stepTrace.EndPosition - travelTrace.EndPosition; var stepTravelled = Vector3.Up * stepDistance; position += stepTravelled; // Offset our position by the height of the step climbed climbedStair = true; IsPushingAgainstWall = false; // Nevermind, we're not against a wall, we climbed a step! WallObject = null; } } } } } if (IsPushingAgainstWall) { // Scale our leftover velocity based on the angle of approach relative to the wall // (Perpendicular = 0%, Parallel = 100%) var scale = ScaleAgainstWalls ? 1f - Vector3.Dot(-travelTrace.Normal.Normal / GripFactorReduction, velocity.Normal) : 1f; var wallLeftover = ScaleAgainstWalls ? Vector3.VectorPlaneProject(leftover, travelTrace.Normal.Normal) : leftover.ProjectAndScale(travelTrace.Normal.Normal); leftover = (wallLeftover * scale).WithZ(wallLeftover.z); WallObject = travelTrace.GameObject; WallNormal = travelTrace.Normal; } else { if (!climbedStair) { var scale = IsSlipping ? 1f : 1f - Vector3.Dot(-travelTrace.Normal / GripFactorReduction, velocity.Normal); leftover = ScaleAgainstWalls ? Vector3.VectorPlaneProject(leftover, travelTrace.Normal) * scale : leftover.ProjectAndScale(travelTrace.Normal); } } } if (travelled.Length <= 0.01f && leftover.Length <= 0.01f) return new MoveHelperResult(position + travelled, travelled / delta); var newResult = CollideAndSlide(new MoveHelperResult(position + travelled, leftover / delta), delta, depth + 1, gravityPass); // Simulate another bounce for the leftover velocity from the latest position var currentResult = new MoveHelperResult(newResult.Position, travelled / delta + newResult.Velocity); // Use the new bounce's position and combine the velocities return currentResult; } if (depth == 0 && !gravityPass) { IsPushingAgainstWall = false; WallObject = null; } return new MoveHelperResult(position + velocity, velocity / delta); // We didn't hit anything? Ok just keep going then :-) } private float CalculateGoalSpeed(Vector3 wishVelocity, Vector3 velocity, bool isAccelerating, float delta) { float goalSpeed; var isSameDirection = velocity.IsNearlyZero(1f) || Vector3.Dot(wishVelocity.WithZ(0f).Normal, velocity.WithZ(0f).Normal) >= 0f; // Is our wishVelocity roughly moving towards our velocity already? var acceleration = IsOnGround ? GroundAcceleration : AirAcceleration; var deceleration = IsOnGround ? GroundDeceleration : AirDeceleration; if (isAccelerating) goalSpeed = acceleration; else goalSpeed = !isSameDirection ? Math.Max(acceleration, deceleration) : deceleration; // Makes movement more responsive especially for flying or rolling if (!IgnoreGroundSurface && GroundSurface != null) goalSpeed *= GroundSurface.Friction; // Take into account the ground's friction goalSpeed *= delta; return goalSpeed; } private Vector3 CalculateGoalVelocity(float delta) { bool shouldIgnoreZ = IgnoreZ || (IgnoreZWhenZero && WishVelocity.z.AlmostEqual(0f)); var wishVelocity = shouldIgnoreZ ? (WishVelocity.Normal * WishVelocity.Length).WithZ(Velocity.z) : WishVelocity; var isAccelerating = shouldIgnoreZ ? wishVelocity.WithZ(0f).Length >= Velocity.WithZ(0f).Length : wishVelocity.Length >= Velocity.Length; var goalSpeed = CalculateGoalSpeed(wishVelocity, Velocity, isAccelerating, delta); var goalVelocity = Velocity.MoveTowards(wishVelocity, goalSpeed); return shouldIgnoreZ ? goalVelocity.WithZ(Velocity.z) : goalVelocity; } public bool TryUnstuck(Vector3 position, out Vector3 result) { var velocityLength = _lastVelocity.Length + SkinWidth; var startPos = position - _lastVelocity.Normal * velocityLength; // Try undoing the last velocity 1st var endPos = position; for (int i = 0; i < MaxUnstuckTries + 1; i++) { if (i == 1) startPos = position + Vector3.Up * 2f; // Try going up 2nd if (i > 1) startPos = position + Vector3.Random.Normal * ((float)i / 2f); // Start randomly checking 3rd var unstuckTrace = BuildTrace(_shrunkenBounds, startPos, endPos); if (!unstuckTrace.StartedSolid) { result = unstuckTrace.EndPosition - _lastVelocity.Normal * SkinWidth; return true; } } result = position; return false; } /// /// Debug don't use /// /// /// /// private bool TestPosition(Vector3 position, string title) { var testTrace = BuildTrace(_shrunkenBounds, position, position); if (testTrace.StartedSolid) { Log.Info($"[{RealTime.Now}]{title} {GameObject.Name} started solid at {position} against {testTrace.GameObject}"); return true; } return false; } protected override void OnFixedUpdate() { base.OnFixedUpdate(); if (!ManuallyUpdate && Active) Move(); } }