[Released] Kinematic Character Controller

Kinematic Character Controller a relatively low-level character controller solution that is not tied to any specific game genre and is made to be cleanly integrated into any project/architecture with as little friction or bloat as possible. Instead of using rigidbody physics, it uses a "collide and slide" algorithm that makes its movements perfectly fluid, precise and responsive. Note that its "kinematic" nature means that interactions with rigidbodies must be explicitly scripted, and that they won't happen automatically.

Asset store page
WebGL Demo
Release Notes
Upgrade Guide

Here is a showcase of the example character included in this package:

Feel free to ask questions here if you have any.

enjoy!

 

Looks pretty impressive, those steps and rotating platforms look super smooth. Nice job.

 

Any idea how it performs compared to the unity built-in character controller?

 

I haven't compared, because it is not really a direct comparison. Despite being relatively "low-level" compared to most of the other CC's available on the store, this character controller still is more high-level than Unity's CC. (due to things like moving platform handling, etc...)

However, I did make a stress test where I had 800 of these characters running at 60 fps on my machine (I have a 3 year old mid-high range Core i5). A single character's update takes about 0.07 ms in a build

 

Very impressive footage. I've been battling with this crap for ages (well, you already know), but it looks like you beat me to it!

 

Looks nice. How about some kind of playable demo?

 

I will see about releasing a WebGL build shortly. Stay tuned

 

https://puu.sh/xM2B7/6bff04d917.webm

Lel.

Really nice controller this one, I'm definitely scrapping mine, it's utter S*** in comparison. :C

 

Haha... oops. I'll see if I can make a more elegant "uncrouching" logic (there is none at the moment)

nice find

 

Haha, apart from crouching the main feature that imo could be generic enough to warrant investigating would be 'forced motion', things like Genji dashes in Overwatch, or perhaps crouch-slides in games like Far Cry 3/4 or Dishonored. In these situations you want different logic for movement (straight forward in view direction for Genji, or low friction and perhaps faster down slopes for sliding), but still need robust collision checking. It might not be suitable for you to implement, but some direction on achieving things like that would probably be helpful!

As for uncrouching logic, I think all that is needed is to check if there is space to stand, and remain crouched if not.

 

A configurable feet size(if it doesn't already exist?) would be nice, so you can configure how far out on an edge you can stand before gravity kicks in.

 

The way things work when you wish to create you own character controller with this system is that you create a class that inherits from 'BaseCharacterController', and you simply implement all abstract methods. For example; there is an UdateVelocity() method in which you must simply return the velocity you want your character to have right now

To implement something like 'forced motion', all you would have to do is that if you're in a standard movement state, you return what the ExampleCharacterController is returning right now.... but if you're in a 'dash' state, you'd return a constant vector that corresponds to the original dash velocity for as long as the dash persists.

I will most likely expand the ExampleCharacterController with several movement examples (like dashes, swimming or double jumps) in order to give you guys a better idea of how all this could be done. This would come in a later update

yup, will do that in the next update

 

Good news; this setting already exists! It's in KinematicCharacterMotor, and it's called "MaxGroundedDistanceFromLedge"

In other words: "what is the maximum distance between your center and the ledge at which you can still be considered stable on the ground"

 

Let me summarize all of the initial feedback I've gathered so far in here and from owners:

• There should be a browser demo
• There should be more examples for things like rootMotion, swimming, dashing, etc....
• There should be a way to activate/deactivate the character physics completely
• Uncrouching should be handled better
• Documentation should more clearly explain how to make a character controller from scratch (with a real example)

I'll be working on an update that solves all of this over the next few days

 

Hey PhilSA, I've done some initial playing around with the Kinematic Character Controller and here are a couple things I've noticed:

1. You can't jump while sliding. It looks like the jumping code is checking if the controller is grounded in order to jump. I haven't looked yet but I assume that sliding is handled as if the character is no longer grounded, which means you'd have to dig into the character motor to fix this. I think ideally we need some way of differentiating between being in the sliding state and the not-grounded state. This would also be useful for triggering animations for sliding as you could simply check "KinematicCharacterMotor.IsSliding" (as an example).
2. The second thing I found is the only real bug I've run into so far. It's best described by this gif, but essentially the character controller will not be able to step up steps while the planet is in a certain rotation.

 

PartyBoat: I don't think this is meant as a generic sliding mechanic. It's more like a way to separate walls from ground. The controller should give you enough environmental information to implement your own sliding mechanic with ease, that you can tune to your liking.

 

@PartyBoat is right about the fact that if you wish to know if you're standing on something even though you're not "grounded", you have no other option than to modify KinematicCharacterMotor. Ideally, KinematicCharacterMotor is the big complex thing that 99% of users shouldn't ever have to touch, so I'll definitely add something to fix this. Right now I'm thinking it could store some kind of "GroundProbingHit", which would be the entire RaycastHit that the ground probing phase detected, whether it was grounded or not. From this you could access the collider, the normal, etc.....

I'll look into the planet stairs bug too

EDIT: I added my current task list at the bottom of my first post, so you guys know what I'm working on. I'll keep this updated at all times

EDIT2: Just solved the stairs problem on the planet. It actually revealed a pretty big flaw in my ground detection code whenever the character wasn't completely upright. Big thanks for bringing this to my attention. The fix will be part of the next update

 

Update: Added a WebGL demo! (Firefox is highly recommended)
https://phil-sa.itch.io/kinematiccharactercontroller?secret=rjRvT8GfZCAXEkevCF92TV07UQ

 

It definitely feels smooth, and it works great on Unity Terrains?

 

It does work just as good on unity terrain too. I'll update the browser demo with a small terrain example later today

(I left out the big terrain you see in the video because it was too rendering-heavy for WebGL and it affected framerate a bit too much)

EDIT: Browser demo has been updated with terrain

 

Update 1.1 has been submitted for review and will be coming to the store shortly. When it releases, it will contain the following changes:

Spoiler: Update 1.1

- Added a "HandlePhysics" method for enabling/disabling collision processing in the KinematicCharacterMotor
- Added the ability to give an arbitrary center to the character's capsule
- Polished crouching behaviour
- Fix a bug with step handling at non-standard orientations
- Added more information about grounding status, as well as an "Allow jumping while sliding" option on the ExampleCharacterController
- Fixed unremovable Rigidbody and Capsule components due tu being set to NonEditable
- Vocabulary change: "Grounded" becomes "Stable"

For the next update, I will be focusing on creating a very detailed step-by-step tutorial that will walk you through the creation of a full character controller from scratch using the Kinematic Character Controller system (basically, the tutorial will re-create the "ExampleCharacterController" and add more stuff to it). The tutorial will be divided in a series of "exercises" that each focus on a specific feature to implement. Here is my currently planned list of exercises:

1. Player, Character and Camera setup
2. Basic movement and gravity
3. Jumping, double-jumping, and wall-jumping
4. Detecting landing and un-grounding
5. Adding impulses and explosion forces
6. Crouching
7. Multiple movement modes setup
8. Dashing
9. Swimming mode
10. NoClip/Spectator mode
11. Animation and Root motion setup
12. Passing through teammates only
13. Climbing a ladder
14. Navigating a navmesh

Additional exercise suggestions are welcome

 

I have been playing around your character controller, and I must say it feels absolutely fantastic!
I see you're thinking of adding a detailed step-by-step tutorial covering a number of topics, which is very nice to hear.

One recommendation I would have is to have a few more example-scenes / example controllers.
Maybe a very simple 3d platformer where you use jumps/walljumps/moving platforms and you reach a goal?

 

Sounds like a good idea. Once the exercices are finished, maybe I could do examples for:

• Quake-like FPS controller
• Mario-like platformer controller
• Zelda-like adventure game controller

Another request I've had is to see if I could add a "non-kinematic" mode to help with physics interactivity (making your character be able to swing on physics ropes, etc...). It would make you lose a bit of "snappiness", but make you gain a lot of physics interactivity in return. This is definitely a longer-term project, but I'll be looking into it at some point

 

Update 1.1 now released on the store

(release notes available on the store page)

 

"full freedom of writing their own game-specific movement code, but want to have a strong foundation to start with"
This is exactly what I've been wishing for. I've been using the super cc but it has some bugs, mesh colliders are slow and I'm not too keen on the state machine it's using. I'm sure you're aware of it though, I remember seeing your name in some old threads.

How well does your controller handle fast movement and thin walls?
Do those physics cubes in your demo need anything special done to them or are they just a rigidbody and collider?
The controller inherits the velocity from the moving platforms in the demo. Can this be disabled?

 

yup... it was the thread in which we convinced Unity to add Physics.ComputePenetration() to the engine, and made my Kinematic Character Controller possible!
https://forum.unity.com/threads/we-need-a-way-to-detect-and-resolve-collision-hits-manually.379699/

I'd say it handles it pretty well

They are just regular rigidbodies with no special component attached. And the KinematicCharacterController treats those the same as moving platforms internally, so you can stand on them and move along with them.
https://i.gyazo.com/6705ea83b10ca5b988b658bec3f53089.mp4
The only downside compared to moving platforms, as you may notice in the video, is that the position/rotation tracking of standing on non-kinematic rigidbodies is always one fixedUpdate late. There is no solution to this aside from coming up with a very specific physics update loop using Physics.Simulate(), but for now this is out of the scope of this character controller, as it would probably break most people's projects. I may consider writing some doc on how to accomplish this at some point, though

Not in the current version, but I am adding a checkbox for this right now.
Either way, removing this manually would be very easy. There a chunk of code in KinematicCharacterMotor.cs that handles this, and you could simply comment it out:

 

Here's a little progress update on the documentation overhaul. I have been preparing a "walkthrough" document that gives you detailed step-by-step instructions on how to create a full custom character controller from scratch, using the KinematicCharacterMotor component.

Here are the sections that I have completed so far:

• Player, Character & Camera setup
• Basic movement and Gravity
• Simple jumping, Double Jumping, Wall Jumping
  
• Detecting landing and leaving ground
  
• Adding velocities and impulses
  
• Crouching
  
• Orienting towards arbitrary up direction
  
• Creating a moving platform
  
• Custom collision filtering
  
• Multiple movement states setup
  
• Charging/Dashing state
  
• NoClip state
  
• Swimming state

And here's what's left to do as of right now:

• Climbing a ladder
  
• Root motion example
  
• Navmesh usage example

For every section of the walkthrough, there is a corresponding folder in the project that contains all the tutorial code and scenes associated with that section.


I believe this will really teach you everything you need to know in order to get started with Kinematic Character Controller. You can expect this walkthrough (and several fixes/tweaks I have made along the way) to be available in update 1.2 in a very near future!

 

Hello there, nice demo,

How does it compare to SuperCharacterController under the hood ?
Are the movement and jump mostly deterministic ? I'm asking because I think it would be great to use this kind of controllers in a network environment, using it for client side prediction and move forward in time other players to compensate lag.
How feasible do you think this is to add as a feature ?

 

SuperCharacterController is a fantastic character controller, and it was my initial inspiration for Kinematic Character Controller. However; it was built at a time where Unity was severely lacking crucial physics functionality. This is why the author of SuperCharacterController and I ended up trying to convince Unity to add Physics.ComputePenetration() to the engine (he is Iron-Warrior). To solve this problem, SuperCharacterController used a custom solution that relied on three spheres on the character to roughly represent a capsule that could resolve collisions, and that used custom scripts that you had to put on mesh colliders in order to "bake" the mesh information. It was the only way to make it work at the time, but it was far from ideal. Kinematic Character Controller makes good use of the newly-added physics methods, which is why it absolutely requires 2017.1 (or 5.6.1p1. You you can't go any earlier than that)

I did my little research while making this controller. I studied these excellent resources to make sure I wasn't doing anything I would later regret when it comes to networking:
http://www.gabrielgambetta.com/client-side-prediction-server-reconciliation.html
https://gafferongames.com/post/deterministic_lockstep/
http://www.gdcvault.com/play/1014345/I-Shot-You-First-Networking
http://schedule.gdconf.com/session/overwatch-gameplay-architecture-and-netcode (this one is unfortunately unavailable to GDCVault non-members)

The movement is as deterministic as floating-points allow. Which means; it is deterministic enough to simulate movements for client-side prediction using only inputs. This is one of the many advantages of it being "kinematic" and not relying on rigidbody physics.

However, it is not deterministic enough to make clients only simulate with inputs for an entire game without ever synchronizing anything with the server. Floating-point errors would kick in at some point in that situation. In the first half of this presentation, there is a team that talks about their experience with making a 100% deterministic online game by building an entirely separated C++ backend for physics & simulation that uses double values instead of float. And the takeaway was.... development was a nightmare. In the end, floating-points + synchronization will do the job just fine

 

Let me know if you need a proofreader for the new docs.
I haven't been able to spend too much time hands on with it yet, so I'm looking forward to more documentation to examine.

 

Hey, what about bunny-hopping (strafe jumping) and surfing? I mean like in CS 1.6 (movement similar to quake).

- Would be cool if possible ^^

 

Since b-hopping is purely a question of how you handle input and velocity, it would be something that users would implement in their custom movement code that tells the KinematicCharacterController how to move. In other words; yes, it's entirely possible to do this with this controller, but it doesn't come pre-packaged with it

b-hopping happens because of a simple little math mistake in the way velocity is limited. Here are some resources that explain it:
http://flafla2.github.io/2015/02/14/bunnyhop.html
https://steamcommunity.com/sharedfiles/filedetails/?id=184184420

 

Here's a little preview of it for now: https://docs.google.com/document/d/1buvW2e2hDGAxsSRZekjkn0TNkU8diWrgu5BnNEES5Qo/edit?usp=sharing

It isn't of much use without the sources that go with it, but it should all land on the asset store within a few days

 

Nice! Skimmed through it a couple times and read it properly once, and it's quite easy to follow even without the project alongside.

Very very good stuff. Probably going to dive in to reimplementing my character controller tomorrow.

 

Without a doubt the new go-to in Character Controller code. Thank you!

 

Update 1.2 now released!
https://www.assetstore.unity3d.com/#!/content/99131

Here's what's new:

• A complete "Walkthrough" document and project folder was created to walk you step-by-step through the creation of an entire custom character controller. Open up Walkthrough.pdf to get started, and follow along with the sub-folders for each section in the "Walkthrough" folder
  It covers topics such as: Basic setup, jumping, double-jumping, swimming, climbing ladders, using root motion, creating moving platforms, using nav meshes, etc, etc.....
  
  
• Overhaul of the "UserGuide" document. It now acts more as an API reference, and contains a streamlined "How to use this package" section that should shed some light on how to get started with Kinematic Character Controller and what to expect of it
• Added the option to restrict character movement to a plane ("Planar Constraint", in the KinematicCharacterMotor). Very useful for 2.5D games
• Improved rotation handling in ExampleCharacterController
• Added an extra parameter to the OnMovementHit and OnGroundHit callbacks which tell you if the character would consider itself "stable" on this hit. The KinematicCharacterMotor already needs to calculate this either way, so it saves you from having to re-check if the character would be stable, and saves on performance

 

Hey, quick question:

The demo doesn't really touch too much on the subject of sliding down slopes that are too steep.
There's only one really steep slope (or you can try dropping from some walls).

I wanted to know if the controller reduces fall speed when "falling down slopes".

When in normal free-fall, the character should obviously keep accelerating (and in games you often have some upper limit), but when you fall against a 85° slope, some character controllers slow down your fall a bit if you move against the wall/slope.
In other words: the player can somehow reduce their falling speed by moving against any slope that is <90°. Imho moving against a really steep slope while in free fall should not give you any upwards momentum / reduce their falling speed.

I hope that's understandable, if not, let me know and I'll try to reformulate it

I saw that problem in a few other controllers, so I'm not sure if that isn't the case here as well.

If this controller doesn't have that problem, then maybe you should add a few really high and steep slopes and a teleporter that puts you on top of them.

 

The default behaviour in this example is that the speed just keeps accelerating up to a certain limit just like it does when free-falling. However, since you are in full control of determining what the character's velocity is at any time, you can implement this behaviour quite easily.

Here's an example of what happens if we take the example character controller code and simply add a few lines that clamps the velocity to 2f if we are not stable on the ground's slope but have found a ground surface:

https://gyazo.com/e350d18f8fb991d80b807bf6a434138b.mp4

 

That means if the player moves against the wall in your example, neither the accumulation of downwards momentum will be impacted, nor will the velocity drop to <2f?

Because in the demo it feels like I can slow my fall a little bit by moving against the wall. (Character controller will deflect the movement into the wall to the tangent of the wall - which points mostly upwards)

Can you elaborate a bit on how exactly the system calculates "deflections".
In the opening post you mentioned that it will slide along a wall, meaning walls fully deflect the direction - speed stays the same but direction changes because the wall blocks you.

Or in other words:
When you move up a slope, will the character controller
a) Move you only on the XZ plane and rely on the physics engine depenetration to not get stuck in the ground? (this would likely ensure that the problem I'm talking about doesn't appear)
or
b) When moving, calculate the deflection against the ground, making your "move" have an non-zero Y component. - meaning with enough "movement force" a player could climb a slope even if it is too steep for them.

Sorry for the intense questioning haha, but I'm thinking about buying this asset, and I don't want to work around "by design" problems

 

So there are 4 cases, basically. Here when I say "stable", I mean that our character is on a ground surface and that the slope of that surface is beneath the max slope angle threshold of the character

• If we're stable and moving against something we'd be stable on (like moving onto a small slope):
  • velocity is reoriented vertically (relatively to the character's up) with no loss in magnitude
• If we're stable and moving against something we'd be not stable on (like moving against a slightly-angled wall):
  
  • velocity is projected as if we were moving against a 90 degree wall, so that the character won't "bump" onto the wall when moving against it. Velocity loss will occur due to projection
• If we're not stable and moving against something we'd be stable on (like being in air and landing on a stable surface):
  
  • Velocity will first be projected on character up so that you don't slide down slopes while jumping in place. Then, the result is projected on the ground normal
• If we're not stable and moving against something we'd be not stable on (like sliding on an angled surface):
  
  • velocity is simply projected on the surface normal

The only case where the speed stays the same is if you're moving against something that doesn't block you (like the spiky terrain in the demo). The slope angle of these spikes is beneath your max slope angle, so velocity is reoriented along the slope instead of being projected. The result is that absolutely no velocity loss or deviation in trajectory occurs, and you can move over those spikes in a perfectly straight line at a constant pace.

The answer is definitely not b). You could ram into a slightly-angled wall at nearly-infinite speed and your character would not move up by a single millimeter: https://i.gyazo.com/be412a63591d122a8b9be0fd01f261bf.mp4
Although if you needed the bump to happen, it would simply be a matter of commenting 2-3 lines of code. Perhaps I could turn it into an option in the inspector for future releases.

But the answer isn't quite a) either. Suppose you give the character a velocity that would move it by (10, 0, 0) over the next fixedUpdate, and that you'll be moving onto a slope in that direction. Here's what'll happen:

1. the character stores the total length of the movement it is supposed to do (10)
2. the character will send a capsule cast in that move direction with a length equal to the remaining movement
3. if the cast hits anything the character can be stable on, it'll calculate a new direction reoriented on that slope, and substract the cast's distance from the total movement magnitude that has to be performed.
4. Repeat steps 2 and 3 until the entire movement magnitude of 10 was consumed
5. Move the character to the resulting position

So the character moves mainly with "sweeps" that detect and solve collisions before they actually happen

 

Thanks for the elaborate explanation, that's what I was hoping for.
Will buy soon

 

This looks like it would work in my scenario but wanted to double check.

I have moving platforms (ships) that are comprised up of a bunch of small box colliders parented to a rigidbody moved with forces. So the main question that comes to mind is if the platform being composed like this will cause issues. If it helps visualize/understand it better the ships are player built from a variety of premade blocks attached to the rigidbody hull (which is 1-3 rigidbodies connected with fixed joints).

 

yes, it would work for this. Here I added a bunch of separate box colliders as children of one of the moving platforms, and it works: https://i.gyazo.com/5410c887b166c5a51686cd2673d7da03.mp4

You can add any sort of collider hierarchy under a PhysicsMover (the component for moving platforms) and it'll behave as expected

 

Hello!
I am currently using the built-in character controller of unity and its .Move function that takes absolute motion deltas. Does your character control have a similar (deterministic) function?

My problem is the following:
I have an online game with a client-side prediction ala Gabriel Gambetta. If I stay next to a wall (wall is left of the player) and call eg cc.Move ((Vector3.forward + Vector3.left) * speed * dt); and the wall ends during this movement the cc will not move left after the end of the wall. It will go straight forward until the next .Move call.

I think this problem is because the builtin cc is only looking for collisions at the beginnig of a move and not updating it during this. And normally this is not a problem because you are calling .Move at high rate in Update() or FixedUpdate() but for my prediction code i cant use it like this. I have to call it when the input changes.

I hope you can understand what I mean. Do you think I can solve this problem with your cc?
Greetings.

 

I think you'd have the same problem with any character controller, including KinematicCharacterController.
The solution is that when doing some prediction/input simulation, you need to sub-divide that simulation over several steps representing your usual deltaTime. So let's say you need to simulate 1 second of inputs, you'd call Move() about 50 times in a row, each with the input movement magnitude divided by 50

 

Hi, I just purchased and integrated KinematicCharacterController. Overall I am very happy with the clean design and flexibility. However for some reason it really is bogging down my performance. I have only a couple of dozen characters running around in a large, somewhat cluttered island, however I am seeing 60% of my CPU time going into the Physics.OverlapCapsuleNonAlloc method in the motor, resulting in a poor frame rate around 20fps. Do you have any guidance on how to get higher performance? If you have 800 characters moving simultaneously in a complex environment with 60fps, I must be doing something wrong.

 

Hi,
Yeah that doesn't sound normal at all. I have a few questions to get started:

1. What version of Unity are you using?
2. What sort of CPU do you have?
3. If 2017.2 and up, can you go in Edit > Project settings > Physics and turn off "Auto Sync Transforms", and see if it changes anything?
4. Do you have any large non-convex mesh colliders in the scene?
5. Is your island's ground just a terrain collider, or is it a bunch of mesh colliders? If it's a terrain, what is its "Heightmap Resolution"?
6. Can you take a screenshot of the profiler in deep profile mode, showing the expanded costliest tasks as best as you can? (something like this)
7. In Edit > Project Settings > Time, how much is your "Fixed Timestep"?
8. If you put the same amount of characters in a simpler scene, like on a cube for example, does it greatly reduce the cost of the character update, or does it remain suspiciously high?

 

Quick question. What is the suggested approach to anchoring the controller to another transform? Will just setting velocity to 0 and moving the controller transform directly with position cause any issues?

 

Btw really like the controller. One minor thing, would be nice if the BaseCharacterController abstract methods were private, since you can make them protected/public in the implementing class, but you can't go the other way.

 

Sorry I mean't protected not private