Forward-Right-Up Coordinate System

Introducing the FRU system

All major 3D content creation tools use a Cartesian coordinate system (X, Y, and Z) to position and rotate objects. However, the specific interpretations for which axes (X, Y, or Z) represent which directions (such as left/right, up/down, and front/back) are different between tools. In addition, the way rotations are modeled—known as the handedness of the coordinate system—also varies between different tools.

To better align Verse and UEFN with emerging standards in 3D content creation, we're making two fundamental changes to our coordinate system presentation.

First, instead of labeling coordinate axes with "X", "Y" and "Z", we're introducing more descriptive axis names:

• Forward (formerly X)

• Right (formerly Y)

• Up (formerly Z) 

Second, the Verse.org spatial math module is moving to contain explicit handedness functions only when handedness is applicable. For example, instead of having an implicit CrossProduct mapping to the engine's current handedness choice, Verse now has explicit CrossProductLeftHanded and CrossProductRightHanded. This helps to ensure that Verse code written today will be valid as the industry's standards emerge and evolve.

Who Does This Affect

This is the first part of the rollout and the changes are currently limited to the API. This means that for now, you will continue to see the XYZ coordinate system in the UE/UEFN outliner and editor. Keep the following in mind:

• The Verse.org module transforms and the UnrealEngine.com module transforms are both running at the same time within the Verse API and in UEFN. If you use Verse.org module transforms, it uses the FRU system. If you use UnrealEngine.com module transforms, it uses the XYZ system.

• If you are using API functions that use both Verse.org module transforms and UnrealEngine.com module transforms in the same file, the type names need to be qualified by their path to avoid any ambiguity between the two modules. This is shown in the example snippet below.

  Verse

  Type names qualified by path

  using { /UnrealEngine.com/Temporary/SpatialMath }
  using { /Verse.org/SpatialMath }
  
  my_class := class:
  	MyUnrealEngineVector:(/UnrealEngine.com/Temporary/SpatialMath:)vector3 = (/UnrealEngine.com/Temporary/SpatialMath:)vector3{}
  	MyVerseVector:(/Verse.org/SpatialMath:)vector3 = (/Verse.org/SpatialMath:)vector3{}
  

  using { /UnrealEngine.com/Temporary/SpatialMath } using { /Verse.org/SpatialMath } my_class := class: MyUnrealEngineVector:(/UnrealEngine.com/Temporary/SpatialMath:)vector3 = (/UnrealEngine.com/Temporary/SpatialMath:)vector3{} MyVerseVector:(/Verse.org/SpatialMath:)vector3 = (/Verse.org/SpatialMath:)vector3{}
  Copy full snippet(6 lines long)

• Scene Graph has converted from UnrealEngine.com module transforms to Verse.org module transforms. This means that Scene Graph now only uses the FRU coordinate system.

• The Verse Digest uses fully-qualified verse identifiers to disambiguate between transform types defined in the UnrealEngine.com/Temporary/SpatialMath and Verse.org/SpatialMath modules.

To learn more about the Unreal Engine coordinate system in general, see Coordinate System and Spaces in Unreal Engine.

Converting from XYZ to FRU

If you are using any existing API functions that have switched to the Verse.org module transforms (FRU), you need to convert your user-defined UnrealEngine.com transforms (XYZ) to use FRU, or use the newly created FromTransform conversion functions. In this section you can find several potential conversion problems and the solutions for them.

Constant or Variable Type Ambiguity

With recent changes to the Verse API, both UnrealEngine.com/Temporary/SpatialMath and Verse.org/SpatialMath define the types vector3, rotation, and transform. As a result, type ambiguity will arise if you include both domains in your verse file.

If your Verse file uses any of those three types, and include 

Type Ambiguity Example

The following Verse file imports both the UnrealEngine.com/Temporary/SpatialMathmodule path and the Verse.org/SpatialMathmodule path, and the user-defined class uses the unqualified type vector3:

using { /UnrealEngine.com/Temporary/SpatialMath }
using { /Verse.org/SpatialMath }

my_class := class:
	MyVectorOne:vector3 = vector3{}	
        #Compile Error: Identifier vector3 could be one of many types: UnrealEngine.com.Temporary.SpatialMath.vector3 or Verse.org.SpatialMath.vector3
	MyVectorTwo:vector3 = vector3{}	
        #Compile Error: Identifier vector3 could be one of many types: UnrealEngine.com.Temporary.SpatialMath.vector3 or Verse.org.SpatialMath.vector3

As a result, the type ambiguity causes a compile error if you attempt to compile this file since the compiler does not know whether to compile MyVectorOne and MyVectorTwo as an UnrealEngine.com vector3 type, or a Verse.org vector3 type. The user has not given the compiler enough information for it to know which type is indicated.

To resolve this compile error, you must path qualify the type of vector3 each variable uses. There are several different ways you can path qualify these constants to resolve the error:

• You can fully qualify any constant or variable of type vector3, as shown in the code snippet below.

  Verse

  Constant or Variable Type Ambiguity - Solution 1

  using { /UnrealEngine.com/Temporary/SpatialMath }
  using { /Verse.org/SpatialMath }
  
  my_class := class:
  	MyVectorOne:(/UnrealEngine.com/Temporary/SpatialMath:)vector3 = (/UnrealEngine.com/Temporary/SpatialMath:)vector3{}
  	MyVectorTwo:(/Verse.org/SpatialMath:)vector3 = (/Verse.org/SpatialMath:)vector3{}
  

  using { /UnrealEngine.com/Temporary/SpatialMath } using { /Verse.org/SpatialMath } my_class := class: MyVectorOne:(/UnrealEngine.com/Temporary/SpatialMath:)vector3 = (/UnrealEngine.com/Temporary/SpatialMath:)vector3{} MyVectorTwo:(/Verse.org/SpatialMath:)vector3 = (/Verse.org/SpatialMath:)vector3{}
  Copy full snippet(6 lines long)

• You can qualify a constant or variable from the /Verse.org module:, as shown in the code snippet below.

  Verse

  Constant or Variable Type Ambiguity - Solution 2

  using { /UnrealEngine.com/Temporary/SpatialMath }
  using { /Verse.org } # Change the module path to avoid import ambiguity
  
  my_class := class:
  	MyVectorOne:vector3 = vector3{}
  	MyVectorTwo:SpatialMath.vector3 = SpatialMath.vector3{} # Specify the submodule

  using { /UnrealEngine.com/Temporary/SpatialMath } using { /Verse.org } # Change the module path to avoid import ambiguity my_class := class: MyVectorOne:vector3 = vector3{} MyVectorTwo:SpatialMath.vector3 = SpatialMath.vector3{} # Specify the submodule
  Copy full snippet(6 lines long)

• You can qualify a constant or variable from the /UnrealEngine.com module, as shown in the code snippet below.

  Verse

  Constant or Variable Type Ambiguity - Solution 3

  using { /UnrealEngine.com/Temporary } # Change the module path to avoid import ambiguity
  using { /Verse.org/SpatialMath }
  
  my_class := class:
  	MyVectorOne:SpatialMath.vector3 = SpatialMath.vector3{} # Specify the submodule
  	MyVectorTwo:vector3 = vector3{}
  

  using { /UnrealEngine.com/Temporary } # Change the module path to avoid import ambiguity using { /Verse.org/SpatialMath } my_class := class: MyVectorOne:SpatialMath.vector3 = SpatialMath.vector3{} # Specify the submodule MyVectorTwo:vector3 = vector3{}
  Copy full snippet(6 lines long)

Scene Graph Type Change

If you are using the Scene Graph APIs in your Verse files and aren't using other APIs that use spatial math, you can change the spatial math types in your Verse code by changing the spatial math module you import with the "using" keyword. For example, if you have the following code:

using { /UnrealEngine.com/Temporary/SpatialMath }

my_component := class<final_super>(component):
	@editable # This change will work regardless of this field being editable or not
	MyVector3:vector3 = vector3{}
	MyVector2:vector2 = vector2{}

you can change it to the following code:

using { /Verse.org/SpatialMath } # Changed the module path

my_component := class<final_super>(component):
	@editable # This change will work regardless of this field being editable or not
	MyVector:vector3 = vector3{} # All transform types now use /Verse.org/SpatialMath
	# MyVector2:vector2 = vector2{} Removed since /Verse.org/SpatialMath does not define a vector2

The only exception is that any vector2 types must be removed or converted to use vector3, since the Verse.org module does not currently define the type vector2.

Function Type Mismatch

Another scenario where you might need to path qualify types, or convert your code, is when:

• A called function or assigned variable expects a type from the UnrealEngine.com module, but is provided a type from the Verse.org module;

• A called function or assigned variable expects a type from the Verse.org module, but is provided a type from the UnrealEngine.com module.

Function Type Mismatch Example

The following two verse files exist in the same project. FileOne.verse defines a function to print a transform from the /UnrealEngine.com/Temporary/SpatialMath module. FileTwo.verse defines a constant transform from the /Verse.org/SpatialMath module and a function to print this value that calls the function from FileOne.verse.

using { /UnrealEngine.com/Temporary/SpatialMath }

PrintTransform(T:transform):void=
	Print("T: {T}")

using { /Verse.org/SpatialMath }

my_class := class:
	T:transform = transform{}

	DoPrint():void=
		PrintTransform(T)	# Compile error: This function parameter expects a value of type (/UnrealEngine.com/Temporary/SpatialMath:)transform, but this argument is an incompatible value of type (/Verse.org/SpatialMath:)transform.

This results in a compile error due to the transform types referring to two different transform types defined in different modules.

To fix this compile error, you must convert the transform type to the correct transform type from the appropriate module. Edit the code in FileTwo.verse to use the FromTransform function, which converts a transform from /Verse.org/SpatialMath to a transform from /UnrealEngine.com/Temporary/SpatialMath.

For a complete list of available conversion functions, see the next section.

# Include /UnrealEngine.com to access conversion functions
using { /UnrealEngine.com }
using { /Verse.org/SpatialMath }

my_class := class:
	T:transform = transform{}

	DoPrint():void=
		PrintTransform(Temporary.SpatialMath.FromTransform(T))  # Compile error fixed after converting transform to the correct type from the proper module

Vector, Rotation, and Transform Type Conversion

The UnrealEngine.com module provides several new conversion functions to convert between the potentially ambiguous types defined in the UnrealEngine.com module and the Verse.org module.

From Unreal Engine Spatial Math to Verse Spatial Math

# Util function for converting a `vector3` from /UnrealEngine.com/Temporary/SpatialMath to a `vector3` from /Verse.org/SpatialMath.
FromVector3<public>(InVector3:(/UnrealEngine.com/Temporary/SpatialMath:)vector3)<reads>:(/Verse.org/SpatialMath:)vector3

# Util function for converting a `rotation` from /UnrealEngine.com/Temporary/SpatialMath to a `rotation` from /Verse.org/SpatialMath
FromRotation<public>(InRotation:(/UnrealEngine.com/Temporary/SpatialMath:)rotation)<reads>:(/Verse.org/SpatialMath:)rotation

# Util function for converting a `transform` from /UnrealEngine.com/Temporary/SpatialMath to a `transform` from /Verse.org/SpatialMath.
FromTransform<public>(InTransform:(/UnrealEngine.com/Temporary/SpatialMath:)transform)<reads>:(/Verse.org/SpatialMath:)transform

From Verse Spatial Math to Unreal Engine Spatial Math

# Util function for converting a `vector3` from /Verse.org/SpatialMath to a `vector3` from /UnrealEngine.com/Temporary/SpatialMath.
FromVector3<public>(InVector3:(/Verse.org/SpatialMath:)vector3)<reads>:(/UnrealEngine.com/Temporary/SpatialMath:)vector3

# Util function for converting a `rotation` from /Verse.org/SpatialMath to a `rotation` from /UnrealEngine.com/Temporary/SpatialMath.
FromRotation<public>(InRotation:(/Verse.org/SpatialMath:)rotation)<reads>:(/UnrealEngine.com/Temporary/SpatialMath:)rotation

# Util function for converting a `transform` from /Verse.org/SpatialMath to a `transform` from /UnrealEngine.com/Temporary/SpatialMath.
FromTransform<public>(InTransform:(/Verse.org/SpatialMath:)transform)<reads>:(/UnrealEngine.com/Temporary/SpatialMath:)transform