Objective

• Resolves Implement collide_and_slide #438
• Supersedes Draft: Collide and Slide Kinematic Character Controller Example (3d) #606
• Almost all kinematic character controllers use an algorithm called "move and slide", aka "collide and slide", "step slide", and similar, at their core
• This algorithm basically says
  • Please move in this direction
  • if you collide with anything, slide along it
  • make sure you're not intersecting with anything, and report everything you collide with
  • see https://www.youtube.com/watch?v=YR6Q7dUz2uk for a video explanation

Solution

• Provide a MoveAndSlide SystemParam with an eponymous move_and_slide function
  • Implemented as a pure function, i.e. it does not mutate the ECS by itself
  • Returns a new position and velocity after movement and sliding along surfaces is complete
  • Every collision encountered during the slide is fed to a callback for optional processing. The callback is allowed to early-abort the slide.
  • Note: Currently, move_and_slide should be used to modify Transform, not LinearVelocity. The returned velocity should be stored elsewhere and passed to the next move and slide call to preserve momentum. ECS integration with LinearVelocity will be added later.
• High level overview: (edited by @Jondolf to match new multi-plane solver)
  1. Initial Gauss-Seidel depenetration pass
  2. For each iteration, until movement is done or max iterations reached:
     • Sweep the shape along the velocity vector
     • If we hit something, move up to the hit point
     • Collect contact planes
     • Project velocity to slide along contact planes
  3. Final Gauss-Seidel depenetration pass
• Inspirations
  • kcc_prototypes: general API shape, various code snippets
  • Box2D's Character Mover: vector clipping and misc. ideas
  • Quake 3's PM_SlideMove: 3D plane solver
  • Solar Ash's implementation, as per Tech Breakdown: Collision Sliding: depenetration
  • Tweets by Philippe St-Amand: new multi-plane solver that projects onto a convex cone, inspired by some of Philippe's ideas
• Prior work in Avian KCC tech and comparison
  • kcc_prototypes:
    • very similar API
    • switched to Q3 plane solver, but then a hard-drive failure erased the progress.
    • no depenetration
  • avian_collide_and_slide:
    • uses Q1 plane solving
    • no depenetration
  • bevy_fps_controller:
    • Q1/Source inspired
    • no exposed collide-and-slide
    • no plane solving
    • no depenetration
• Special thanks to @UndefinedBHVR, who spearheaded a first iteration of collide-and-slide that I was able to iterate on and who's breadcrumbs I followed a lot ❤️
• TODO:
  • Fix some jitter on plane intersections
  • Write docs
  • Add examples to docs
  • Replace the asset links juuuust before merging
    • See Add move_and_slide files avian_asset_files#1

Out of Scope for this PR

• Example KCC implementation
  • This is a deep rabbit hole and I'll leave that as a followup to not bloat this PR.
  • See Add more complete character controller examples #450 for a list of minimal character controllers that should be showcased eventually
  • For now, an integration into https://github.com/janhohenheim/character_controller_experiments will serve as proof that a KCC is doable with this API.
• Changing the existing KCC examples
  • I think these should just be entirely rewritten later on
• predicting intersections with moving bodies
• calculating forces to be exerted onto touching dynamic bodies and vice versa
• minimal examples, for now we just have the in-depth testbeds
• a more diverse 2D testbed: requires parsing SVGs like Box2D

Testing

• 3D testbed
  • bevy run --example collide_and_slide -p avian3d
• 2D testbed
  • bevy run --example collide_and_slide -p avian2d
• integration in https://github.com/janhohenheim/character_controller_experiments

Showcase