feat: sdk physics impulse and force (#7044)

# Pull Request Description

[protocol PR](decentraland/protocol#363)
[js-toolchain PR](decentraland/js-sdk-toolchain#1338)
[sdk-test-scene PR](decentraland/sdk7-test-scenes#49)

this PR implements Explorer part of Impulse/Force applied by the SDK scene

[ref how-to wiki](https://github.com/decentraland/unity-explorer/blob/dev/docs/how-to-implement-new-sdk-components.md)

## What does this PR change?
- add component handling logic
- extract debug from the core logic system for char velocity
- expose new settings to the char controller

## Test Instructions
[QA epic](#7262) 
[sdk-test-scene PR](decentraland/sdk7-test-scenes#49)

to test this feature go to `flutterecho.dcl.eth` where there are different zones for applying force/impulse

Author: popuz

Explorer/Assets/DCL/Character/CharacterMotion/Animation/AnimationStatesLogic.cs

@@ -23,9 +23,8 @@ public static void Execute(float dt,
             in GlideState glideState)
         {
             bool isGrounded = rigidTransform is { IsGrounded: true, IsOnASteepSlope: false } || rigidTransform.IsStuck;
-
             Vector3 velocity = rigidTransform.MoveVelocity.Velocity;
-            float verticalVelocity = rigidTransform.GravityVelocity.y + velocity.y;
+            float verticalVelocity = rigidTransform.GravityVelocity.y + velocity.y + rigidTransform.ExternalVelocity.y;
 
             bool jumpTriggered = jumpState.JumpCount > animationComponent.States.JumpCount;
             bool glidingTriggered = glideState.Value == GlideStateValue.OPENING_PROP && animationComponent.States.GlideState != GlideStateValue.OPENING_PROP;

Explorer/Assets/DCL/Character/CharacterMotion/Components/CharacterRigidTransform.cs

@@ -1,4 +1,4 @@
-using UnityEngine;
+using UnityEngine;
 
 namespace DCL.CharacterMotion.Components
 {
@@ -48,6 +48,20 @@ public class CharacterRigidTransform
         // This flag is set when the rigidTransform is between 2 slopes
         public bool IsStuck;
 
+        // Net external force acting on the character (persistent while source is active, managed by the writer's lifecycle)
+        public Vector3 ExternalForce;
+
+        // Computed acceleration from ExternalForce (a = F / mass), per-frame
+        public Vector3 ExternalAcceleration;
+
+        // Pending external impulse to apply this frame (cleared after applying)
+        // Impulse = instant velocity change: Δv = J / mass
+        public Vector3 ExternalImpulse;
+
+        // External velocity from impulses, forces (jump pads, knockbacks, wind, etc.)
+        // Decays over time via drag/friction
+        public Vector3 ExternalVelocity;
+
         public struct MovementVelocity
         {
             // Current sideways velocity

Explorer/Assets/DCL/Character/CharacterMotion/Settings/CharacterControllerSettings.asset

@@ -172,3 +172,7 @@ MonoBehaviour:
   <HeadIKRemotePlayersDistance>k__BackingField: 10
   <JumpPadForce>k__BackingField: 50
   <AnimationSpeed>k__BackingField: 1
+  <CharacterMass>k__BackingField: 1
+  <ExternalEnvDrag>k__BackingField: 1.5
+  <ExternalGroundFriction>k__BackingField: 4
+  <MaxExternalVelocity>k__BackingField: 50

Explorer/Assets/DCL/Character/CharacterMotion/Settings/CharacterControllerSettings.cs

@@ -1,4 +1,4 @@
-using UnityEngine;
+using UnityEngine;
 using UnityEngine.Serialization;
 
 namespace DCL.CharacterMotion.Settings
@@ -108,5 +108,11 @@ public class CharacterControllerSettings : ScriptableObject, ICharacterControlle
         [field: SerializeField] public float HeadIKRemotePlayersDistance { get; set; } = 10;
         [field: SerializeField] [field: Header("Cheat/Debug/Misc")] public float JumpPadForce { get; private set; } = 50f;
         [field: SerializeField] public float AnimationSpeed { get; private set; } = 1;
+
+        [field: Header("Impulse / External Velocity")]
+        [field: SerializeField] public float CharacterMass { get; set; } = 1f;
+        [field: SerializeField] public float ExternalEnvDrag { get; set; } = 0.5f;
+        [field: SerializeField] public float ExternalGroundFriction { get; set; } = 4f;
+        [field: SerializeField] public float MaxExternalVelocity { get; set; } = 50f;
     }
 }

Explorer/Assets/DCL/Character/CharacterMotion/Settings/ICharacterControllerSettings.cs

@@ -94,5 +94,11 @@ public interface ICharacterControllerSettings
         float WallSlideDetectionDistance { get; }
         float WallSlideMaxMoveSpeedMultiplier { get; }
         float StepOffset { get; set; }
+
+        // Impulse / External Velocity settings
+        float CharacterMass { get; set; }
+        float ExternalEnvDrag { get; set; }
+        float ExternalGroundFriction { get; set; }
+        float MaxExternalVelocity { get; set; }
     }
 }

Explorer/Assets/DCL/Character/CharacterMotion/Settings/OverridableCharacterControllerSettings.cs

@@ -1,4 +1,4 @@
-using DCL.SDKComponents.AvatarLocomotion.Components;
+using DCL.SDKComponents.AvatarLocomotion.Components;
 using DCL.SDKComponents.AvatarLocomotion.Systems;
 using UnityEngine;
 
@@ -366,6 +366,30 @@ public float StepOffset
             set => impl.StepOffset = value;
         }
 
+        public float CharacterMass
+        {
+            get => impl.CharacterMass;
+            set => impl.CharacterMass = value;
+        }
+
+        public float ExternalEnvDrag
+        {
+            get => impl.ExternalEnvDrag;
+            set => impl.ExternalEnvDrag = value;
+        }
+
+        public float ExternalGroundFriction
+        {
+            get => impl.ExternalGroundFriction;
+            set => impl.ExternalGroundFriction = value;
+        }
+
+        public float MaxExternalVelocity
+        {
+            get => impl.MaxExternalVelocity;
+            set => impl.MaxExternalVelocity = value;
+        }
+
         public float HeadIKWeightChangeSpeed
         {
             get => impl.HeadIKWeightChangeSpeed;

Explorer/Assets/DCL/Character/CharacterMotion/Systems/CalculateCharacterVelocitySystem.cs

@@ -1,22 +1,21 @@
-using Arch.Core;
+using Arch.Core;
 using Arch.System;
 using Arch.SystemGroups;
 using Arch.SystemGroups.DefaultSystemGroups;
+using DCL.AvatarRendering.DemoScripts.Components;
 using DCL.Character.CharacterMotion.Components;
 using DCL.Character.CharacterMotion.Velocity;
 using DCL.CharacterCamera;
+using DCL.CharacterMotion;
 using DCL.CharacterMotion.Components;
 using DCL.CharacterMotion.Settings;
-using DCL.DebugUtilities;
-using DCL.DebugUtilities.UIBindings;
 using DCL.Time.Systems;
 using ECS.Abstract;
 using ECS.LifeCycle.Components;
 using UnityEngine;
-using DCL.AvatarRendering.DemoScripts.Components;
 using DCL.CharacterMotion.Utils;
 
-namespace DCL.CharacterMotion.Systems
+namespace DCL.Character.CharacterMotion.Systems
 {
     /// <summary>
     ///     Entry point to calculate everything that affects character's velocity
@@ -27,107 +26,17 @@ public partial class CalculateCharacterVelocitySystem : BaseUnityLoopSystem
     {
         private SingleInstanceEntity camera;
         private SingleInstanceEntity fixedTick;
-        private SingleInstanceEntity entitySettings;
-
-        private readonly ElementBinding<float> cameraRunFov = new (0);
-        private readonly ElementBinding<float> walkSpeed = new (0);
-        private readonly ElementBinding<float> jogSpeed = new (0);
-        private readonly ElementBinding<float> runSpeed = new (0);
-        private readonly ElementBinding<float> jogJumpHeight = new (0);
-        private readonly ElementBinding<float> runJumpHeight = new (0);
-        private readonly ElementBinding<float> jumpHold = new (0);
-        private readonly ElementBinding<float> jumpHoldGravity = new (0);
-        private readonly ElementBinding<float> gravity = new (0);
-        private readonly ElementBinding<float> airAcc = new (0);
-        private readonly ElementBinding<float> maxAirAcc = new (0);
-        private readonly ElementBinding<float> airDrag = new (0);
-        private readonly ElementBinding<float> stopTime = new (0);
-
-        private readonly ElementBinding<int> airJumpCount = new (0);
-        private readonly ElementBinding<float> airJumpHeight = new (0);
-        private readonly ElementBinding<float> airJumpDelay = new (0);
-        private readonly ElementBinding<float> airJumpGravityDuringDelay = new (0);
-        private readonly ElementBinding<float> cooldownBetweenJumps = new (0);
-        private readonly ElementBinding<float> airJumpImpulse = new (0);
-
-        public CalculateCharacterVelocitySystem(World world, IDebugContainerBuilder debugBuilder) : base(world)
-        {
-            debugBuilder.TryAddWidget("Locomotion: Base")?
-                        .AddFloatField("Camera Run FOV", cameraRunFov)
-                        .AddFloatField("Walk Speed", walkSpeed)
-                        .AddFloatField("Jog Speed", jogSpeed)
-                        .AddFloatField("Run Speed", runSpeed)
-                        .AddFloatField("Jog Jump Height", jogJumpHeight)
-                        .AddFloatField("Run Jump Height", runJumpHeight)
-                        .AddFloatField("Jump Hold Time", jumpHold)
-                        .AddFloatField("Jump Hold Gravity Scale", jumpHoldGravity)
-                        .AddFloatField("Gravity", gravity)
-                        .AddFloatField("Air Acceleration", airAcc)
-                        .AddFloatField("Max Air Acceleration", maxAirAcc)
-                        .AddFloatField("Air Drag", airDrag)
-                        .AddFloatField("Grounded Stop Time", stopTime);
-
-            debugBuilder.TryAddWidget("Locomotion: Air Jumping")?
-                        .AddControl( new DebugConstLabelDef("Air Jump Count"), new DebugIntFieldDef(airJumpCount) )
-                        .AddFloatField("Height", airJumpHeight)
-                        .AddFloatField("Delay", airJumpDelay)
-                        .AddFloatField("Gravity during Delay", airJumpGravityDuringDelay)
-                        .AddFloatField("Cooldown", cooldownBetweenJumps)
-                        .AddFloatField("Direction Change Impulse", airJumpImpulse);
-        }
+
+        public CalculateCharacterVelocitySystem(World world) : base(world) { }
 
         public override void Initialize()
         {
             camera = World.CacheCamera();
             fixedTick = World.CachePhysicsTick();
-            entitySettings = World.CacheCharacterSettings();
-
-            ICharacterControllerSettings settings = entitySettings.GetCharacterSettings(World);
-            cameraRunFov.Value = settings.CameraFOVWhileRunning;
-            walkSpeed.Value = settings.WalkSpeed;
-            jogSpeed.Value = settings.JogSpeed;
-            runSpeed.Value = settings.RunSpeed;
-            jogJumpHeight.Value = settings.JogJumpHeight;
-            runJumpHeight.Value = settings.RunJumpHeight;
-            jumpHold.Value = settings.LongJumpTime;
-            jumpHoldGravity.Value = settings.LongJumpGravityScale;
-            gravity.Value = settings.Gravity;
-            airAcc.Value = settings.AirAcceleration;
-            maxAirAcc.Value = settings.MaxAirAcceleration;
-            airDrag.Value = settings.AirDrag;
-            stopTime.Value = settings.StopTimeSec;
-            airJumpCount.Value = settings.AirJumpCount;
-            airJumpHeight.Value = settings.AirJumpHeight;
-            airJumpDelay.Value = settings.AirJumpDelay;
-            airJumpGravityDuringDelay.Value = settings.AirJumpGravityDuringDelay;
-            cooldownBetweenJumps.Value = settings.CooldownBetweenJumps;
-            airJumpImpulse.Value = settings.AirJumpDirectionChangeImpulse;
         }
 
         protected override void Update(float t)
         {
-            ICharacterControllerSettings settings = entitySettings.GetCharacterSettings(World);
-
-            settings.CameraFOVWhileRunning = cameraRunFov.Value;
-            settings.WalkSpeed = walkSpeed.Value;
-            settings.JogSpeed = jogSpeed.Value;
-            settings.RunSpeed = runSpeed.Value;
-            settings.JogJumpHeight = jogJumpHeight.Value;
-            settings.RunJumpHeight = runJumpHeight.Value;
-            settings.LongJumpTime = jumpHold.Value;
-            settings.LongJumpGravityScale = jumpHoldGravity.Value;
-            settings.Gravity = gravity.Value;
-            settings.AirAcceleration = airAcc.Value;
-            settings.MaxAirAcceleration = maxAirAcc.Value;
-            settings.AirDrag = airDrag.Value;
-            settings.StopTimeSec = stopTime.Value;
-            settings.AirJumpCount = airJumpCount.Value;
-            settings.AirJumpHeight = airJumpHeight.Value;
-            settings.AirJumpDelay = airJumpDelay.Value;
-            settings.AirJumpGravityDuringDelay = airJumpGravityDuringDelay.Value;
-            settings.CooldownBetweenJumps = cooldownBetweenJumps.Value;
-            settings.AirJumpDirectionChangeImpulse = airJumpImpulse.Value;
-
             ResolveVelocityQuery(World, t, fixedTick.GetPhysicsTickComponent(World).Tick, in camera.GetCameraComponent(World));
             ResolveRandomAvatarVelocityQuery(World, t, fixedTick.GetPhysicsTickComponent(World).Tick, in camera.GetCameraComponent(World));
         }
@@ -213,19 +122,29 @@ private void ResolveAvatarVelocity([Data] float dt,
             // Apply velocity multiplier based on walls
             ApplyWallSlide.Execute(ref rigidTransform, characterController, in settings);
 
-            // Apply vertical velocity
+            // External forces must run before gravity so ExternalAcceleration.y is available
+            ApplyExternalForce.Execute(settings, ref rigidTransform, dt);
+
+            // Vertical velocity (jump + gravity with effective gravity from external forces)
             ApplyJump.Execute(settings, ref rigidTransform, ref jumpState, ref jumpInput, in movementInput, viewerForward, viewerRight, physicsTick, dt);
             ApplyGravity.Execute(settings, ref rigidTransform, jumpState, in jumpInput, physicsTick, dt);
             ApplyGliding.Execute(settings, in rigidTransform, jumpState, in jumpInput, ref glideState, physicsTick, dt);
 
-            ApplyAirDrag.Execute(settings, ref rigidTransform, dt);
+            // External impulses must run after gravity so it nullify gravity velocity.y
+            ApplyExternalImpulse.Execute(settings, ref rigidTransform);
+
+            // Drag
+            ApplyHorizontalAirDrag.Execute(settings, ref rigidTransform, dt);
+            ApplyExternalVelocityDragAndClamp.Execute(settings, ref rigidTransform, dt);
 
+            // Rotation
             if (cameraComponent.Mode == CameraMode.FirstPerson)
                 ApplyFirstPersonRotation.Execute(ref rigidTransform, in cameraComponent);
             else
                 ApplyThirdPersonRotation.Execute(ref rigidTransform, in movementInput);
 
-            ApplyConditionalRotation.Execute(ref rigidTransform, in settings);
+            if (settings.EnableCharacterRotationBySlope)
+                ApplySlopeConditionalRotation.Execute(ref rigidTransform, in settings);
         }
     }
 }

Explorer/Assets/DCL/Character/CharacterMotion/Systems/CalculateSpeedLimitSystem.cs

@@ -3,16 +3,12 @@
 using Arch.SystemGroups;
 using Arch.SystemGroups.DefaultSystemGroups;
 using DCL.AvatarRendering.DemoScripts.Components;
-using DCL.Character.CharacterMotion.Components;
-using DCL.CharacterCamera;
+using DCL.Character.CharacterMotion.Systems;
 using DCL.CharacterMotion.Components;
 using DCL.CharacterMotion.Settings;
 using DCL.CharacterMotion.Utils;
 using DCL.Time.Systems;
 using ECS.Abstract;
-using ECS.LifeCycle.Components;
-using System;
-using UnityEngine;
 
 namespace DCL.CharacterMotion.Systems
 {