With V3 being released in the near future, this article may be out of date very soon.
Opsive character controllers are premium priced offerings, which come in at the top of the controller price range and help to add that AAA quality to your game by covering lots of edge cases – such as much improved clipping detection for the camera.
Unfortunately, despite the premium positioning (and being called Ultimate), the package ships with some features missing! Swimming and climbing are both extras (while combat will be part of the code package which is the opposite of many controllers setup). The swimming controller is well done (although I would have to argue I prefer some of HAP’s setup better), but the issue is setting it up can be a bit clunky.
The swimming add-on comes with documentation which covers the steps well enough that I was eventually able to debug myself out of crab mode, but not so well as to stop me getting there in the first place.
Why does my character freeze in Crab position!?
So the main issue that made me write this post was that after I set up the character using the documentation, whenever I entered the water my guy suddenly held his arms like a crab and was not able to move except to turn in a circle as the buoyancy lifted him up.
After some pretty exhausting debugging I discovered the mistake (which I’d argue is Opsive’s mistake as much as mine):
In this case, not including the Swimming demo directory means also not importing all of the animations, since they are nested there. The knock-on is that Opsive’s own setup tool then has no animations to attach, so fails silently.
Other tips for setting up Opsive Swimming Add-On
Besides the crabbing issue, I noted a couple more things in the instructions which I found unclear:
“Swimming Animations” – the swimming animations section says to go to the Add-Ons manager to set up your character, this is correct but I want to highlight what I missed: There are tabs installed/available and it is not clear which tab you are on. Make sure to click the installed tab, otherwise you’ll just see the tile that says “installed”, not the UI from the documentation!
“Add the Swim Capsule Collider Positioner preset to the character’s Capsule Collider” – the confusion here is again with demo assets, if you did not import the demo you’ll need to create your own preset, which won’t make it clear what fields to set.
“Start Swim Depth” – we don’t recommend reducing these much from the defaults since you’ll likely find that when swimming across shallow water above a land or rock area, your character will get stuck.
“Diving” – When jumping from the top of rocks etc. you’ll just tombstone every time. The documentation does mention the dive ability and how to add it to the character, but does not mention how to actually trigger it. Below we’ll discuss setting it up if it’s not working.
Setting up Diving and Dive Platforms for Opsive Swimming
So it turns out, no platforms are needed – so good news, there’s no need to put colliders on every terrain edge, Opsive handles this very smartly (they just failed to document it)
 | It turns out the setup tool made some mistakes with my character, so the first thing you should do is check the fields I have highlighted on my character’s dive section: State: This field should have a value of Dive. By default it was blank for me. Angle Threshold: 26 is what the demo used. By default mine was set to 180, which rarely recognized dive points. Object ID: I’m not clear what object this represents. In the demo the value matches the Ability Index field. By default it was -1 for me and leaving it that way did not cause an issue. |
After you ensure that your Dive ability is configured as above, all you need to do is approach an edge which is a suitable distance from the Water surface and importantly press F – not jump!
