API Introduction

Curvy features a full-fledged API you can use to integrate Curvy into your projects. Remember, all Controllers and the whole editor API was written using Curvy's API, no private secrets at all!

The best way to explore Curvy's API is to browse the API reference or explore available properties and methods with intellisense right from Visual Studio or MonoDevelop.

When working with the API you should keep in mind the following code conventions Curvy follows:

  • Methods ending with “Fast” means that caching is being used
  • Methods ending with “INTERNAL” should be considered private and generally not be used. The reason you're seeing them is that we need to access them from editor classes and there's no proper way in C# to hide them from you.
  • Properties usually don't need to be cached by you. Either they're cached internally or fast enough to call them multiple times. Costly operations always use functions - just in case you wonder why some features are properties while others are functions…

This applies for Curvy Spline. A lot of those methods have their equivalent in Curvy Spline Segment

Unit Conversion

TFToDistance()

Converts a given TF value into world units distance from spline's start

DistanceToTF()

Converts a given world units distance value into TF

Getting spline data

Interpolate()

Gets the position for a given TF or F

GetTangent()

Gets the tangent/direction for a given TF or F

GetOrientationUpFast()

Gets the Up vector for a given TF or F

GetOrientationFast()

Gets the rotation for a given TF or F, i.e. LookRotation(tangent,up)

Add/Delete Control Points

Add(), InsertBefore() and InsertAfter()

Adds one or more Control Points

Delete()

Deletes a Control Point

Clear()

Remove all Control Points

Updating

Refresh()

Refreshes the spline (i.e. updates the cache). This is called automatically at the regular Update() call if necessary. The only reason you may need to call this by yourself is if you manipulate the spline by code and want to read data from the spline directly afterwards.

Refresh() rebuilds the cache only if necessary, so calling it multiple times won't affect performance!

Curvy Generator is built from several GameObjects that needs to be properly initialized before you can access it safely. It has an IsInitialized property that you should check before trying to interact with it. For example:

IEnumerator Start ()
{
    // Wait until the generator is fully intialized before accessing it: 
    while (!CurvyGenerator.IsInitialized) 
      yield return null; 
    // now we're safe to use it 
    CurvyGenerator.SomeMethod();}

This is a simple field:

public float Number;

The above code has just a single benefit: it's fast to write. Besides that, it's horrible for a number of good reasons:

  • no input validation
  • setting values might mark your scene dirty though the value hasn't changed
  • no way to react to changes, e.g. refresh something

So, forget the above code. Don't use it! Never! Ever!

Instead, this is the same field (with some input validation added) done the right way:

[SerializeField]
float m_Number;
 
public float Number
{
  get { return m_Number;}
  set
  {
     float v=Mathf.Clamp01(value);
     if (m_Number!=v)
       m_Number=v;
  }
}
 
#if UNITY_EDITOR
        void OnValidate()
        {
            Number = m_Number;
        }
#endif

Heck, that's pretty much code for a simple field. So, why this?

When accessing the field by code the property should be used and you can be sure that input is validated. The serialized field “m_Number” is used by inspectors instead with no input validation, but OnValidate() is called by the editor afterwards, so you can just set the property again to apply input validation and subsequent actions.

Having PropertyDrawers like [Range(0,1)] will add input validation to inspector fields, but then you're missing validation when setting the field from code.

Unity folks do it this way, you should do the same for the above good reasons!

You can set global preprocessor defines to enable/disable several features.

CURVY_SANITY_CHECKS

Activates more sanity checks. This will make Curvy log messages if you use its API incorrectly, helping you debug possible issues. These checks cost some additional CPU time.

CURVY_DEBUG

Collect debug informations (like Curvy Generator execution times) outside the editor and shows additional data in several places