OpenKCC

This project is a sample of the Open Kinematic Character Controller. A Kinematic Character Controller (KCC) provides a way to control a character avatar as a kinematic object that will interact with the environment.

Bunny logo for OpenKCC project - a white bunny with the letters OpenKCC written in outlined boxes in front of it.

OpenKCC is an open source project hosted at https://github.com/nicholas-maltbie/OpenKCC

This is an open source project licensed under a MIT License. Feel free to use a build of the project for your own work. If you see an error in the project or have any suggestions, write an issue or make a pull request, I'll happily include any suggestions or ideas into the project.

Designing Character Controllers Video Introduction

You can see a demo of the project running here: https://nickmaltbie.com/OpenKCC/. The project hosted on the website is up to date with the most recent version on the main branch of this github repo and is automatically deployed with each update to the codebase.

Installation

Make sure to add the required dependencies to your project

In order to use the samples in the project, make sure to also add the following projects to your project.

Install the latest version of the project by importing a project via git at this URL: git+https://github.com/nicholas-maltbie/OpenKCC.git#release/latest

If you want to reference a specific tag of the project such as version v1.0.1, add a #release/v1.0.1 to the end of the git URL to download the package from th auto-generated branch for that release. An example of importing v1.0.1 would look like this: git+https://github.com/nicholas-maltbie/openkcc.git#release/v1.0.1.

To use the latest release, simply reference:

git+https://github.com/nicholas-maltbie/openkcc.git#release/latest

For a full list of all tags, check the OpenKCC Tags list on github. I will usually associated a tag with each release of the project.

Note: before I started using the package format for the project, I manually released a unity package you needed to import. Any version before v1.0.0 will not work to import the project.

If you do not include a tag, this means that your project will update whenever you reimport from main. This may cause some errors or problems due to experimental or breaking changes in the project.

You can also import the project via a tarball if you download the source code and extract it on your local machine. Make sure to import via the package manifest defined at Packages\com.nickmaltbie.openkcc\package.json within the project.

For more details about installing a project via git, see unity's documentation on Installing form a Git URL.

Scoped Registry Install

If you wish to install the project via a Scoped Registry and npm, you can add a scoped registry to your project from all of the com.nickmaltbie packages like this:

"scopedRegistries": [
  {
    "name": "nickmaltbie",
    "url": "https://registry.npmjs.org",
    "scopes": [
      "com.nickmaltbie"
    ]
  }
]

Then, if you want to reference a version of the project, you simply need to include the dependency with a version string and the unity package manager will be able to download it from the registry at https://registry.npmjs.org

"dependencies": {
  "com.nickmaltbie.openkcc": "1.0.1",
  "com.nickmaltbie.screenmanager": "3.0.0",
  "com.nickmaltbie.statemachineunity": "1.1.0",
  "com.nickmaltbie.testutilsunity": "1.0.0",
  "com.unity.inputsystem": "1.0.0",
  "com.unity.textmeshpro": "3.0.0"
}

Tests

If you wish to include the testing code for this project, make sure to add the com.unity.inputsystem and com.nickmaltbie.openkcc to the testables of the project manifest.

  "testables": [
    "com.nickmaltbie.openkcc",
    "com.nickmaltbie.testutilsunity",
    "com.unity.inputsystem"
  ]

Additionally, some of the testing code uses pro builder's api, so make sure to import com.unity.probuilder version 5.0 or newer as well..

Samples

In order to run the samples from the project, you must import the following projects:

The samples in the project include:

  • ExampleFirstPersonKCC - Example first person character controller with a basic test scene.
  • SimplifiedDemoKCC - Simplified character controller with basic movement scripts.
  • Various Collider Shapes - Example collider shapes besides basic capsule for a player.
  • Example OpenKCC and Navmesh - Example navmesh agent controlled by OpenKCC movement engine.

Netcode Example

Using Unity's netcode package I created another example package called com.nickmaltbie.openkcc.netcode with a sample NetcodeExample for an example of setting up the OpenKCC as a networked character controller.

To add the netcode example to your project, you can download it from one of the release branches under the pattern release/netcode/version or from the npm repo with the name com.nickmaltbie.openkcc.netcode. It contains some useful utility classes in addition to the sample.

The sample is hosted online at https://nickmaltbie.com/OpenKCC/Netcode/ but you will need to host a server on a windows/linux/mac machine as the WebGL build for unity does not support opening a server socket within WebGL.

Required packages for samples that are not already included in the project:

{
  "scopedRegistries": [
    {
      "name": "nickmaltbie",
      "url": "https://registry.npmjs.org",
      "scopes": [
        "com.nickmaltbie"
      ]
    }
  ],
  "dependencies": {
    "com.nickmaltbie.recolorshaderunity": "1.0.0",
    "com.unity.inputsystem": "1.4.4",
    "com.nickmaltbie.testutilsunity": "1.0.0",
    "com.unity.netcode.gameobjects": "1.1.0",
    "com.unity.probuilder": "5.0.6"
  }
}

The samples in the project include:

  • ExampleFirstPersonKCC - Example first person character controller with a basic test scene.
  • Mole KCC Sample Character - Example mole character controller for moving around and climbing on objects.

Documentation

Documentation on the project and scripting API is found at https://nickmaltbie.com/OpenKCC/docs/ for the latest version of the codebase.

To view the documentation from a local build of the project install DocFX, use the following command from the root of the repo.

Documentation/build.sh

(Or this for windows)

.\Documentation\build-validation.cmd

The documentation for the project is stored in the folder /Documentation and can be modified and changed to update with the project.

This documentation project is inspired by the project by Norman Erwan's DocFxForUnity

Learning

I will be making a video series discussing how the Open KCC works and going into detail about how the various features work, describing game design in general, and details about the unity engine and virtual environments.

As these videos are created they will be listed here:

Development

If you want to help with the project, feel free to make some changes and submit a PR to the repo.

This project is developed using Unity Release 2023.1.6f1. Install this version of Unity from Unity Hub using this link: unityhub://2023.1.3f1/e00e24c187a5.

Git LFS Setup

Ensure that you also have git lfs installed. It should be setup to auto-track certain types of files as determined in the .gitattributes file. If the command to install git-lfs git lfs install is giving you trouble, try looking into the installation guide.

Once git lfs is installed, from in the repo, run the following command to pull objects for development.

git lfs pull

Githooks Setup

When working with the project, make sure to setup the .githooks if you want to edit the code in the project. In order to do this, use the following command to reconfigure the core.hooksPath for your repository

git config --local core.hooksPath .githooks