[This is preliminary documentation and is subject to change.]

Depending on the way CAINav is built, it will use either the UnityEngine vectors or the CAINav built-in vectors. For Unity users, UnityEngine.Vector3 and UnityEngine.Vector2. For .NET-Only users, org.critterai.Vector3 and org.critterai.Vector2. This is great for Unity users, but means that .NET-users will probably need to marshal between their native vector structures and the CAINav structures.

Advanced users have another option. It may be possible, with only an hour or two of work per version upgrade, to swap your own native vectors into CAINav. This topic will cover the steps to accomplish this.

Overview

In order to swap your own native vectors into CAINav, you'll need to follow these steps:

  1. Validate that your vector API is compatible.
  2. Update the .NET Visual Studio Projects and code. (Mostly a simple search and replace.)
  3. Build and validate vector data compatibility.

Validate API Compatibility

The first step is to make sure your native vector's API is compatible with org.critterai.Vector3. To do this, open the .NET Visual Studio project. It is located in the \build\dotNet directory of the distribution. The source file will be located in the cai-util project. The Vector3 structure is kept very simple, so the likelihood of conflict is minimal.

While you will be validating data compatibility later, it is a good idea to smoke check that now. (Do the order of the fields match?)

Update the Visual Studio Projects and Code

Add a reference to your vector library to each project in the Visual Studio solution.

Throughout the CAINav code the following conditional compile statement is used to control which vector is used:

CopyC#
#if NUNITY
using Vector3 = org.critterai.Vector3;
#else
using Vector3 = UnityEngine.Vector3;
#endif

So all you need to do to swap in your own vector is to do a global search and replace. Find "using Vector3 = org.critterai.Vector3;", and replace it with your own. For example: "using Vector3 = MyEngine.Vector3f;"

Browse to the Vector3 source file in the cai-util project and comment out all code. This makes sure that errors don't accidentally result in the CAINav vector still being referenced somewhere.

Finally, build the solution. It your API is truly compatible, the build should complete without errors.

Validate Data Compatibility

The final step is to check data capatibility. (Is the internal data format of your vector the same as the CAINav vector?) To do this, write some test code that uses the new libraries and run the following test methods:

TestVector(Vector3) and TestVectorArray(array<Vector3>[]()[][], Int32, array<Vector3>[]()[][])

If the input and output of these test methods matches exactly, then you are good to go. If the tests fail, then you know that there is some sort of problem and you won't be able to use your native vectors.