Which way is up?

There are various conventions for which vector is "up" in 3D world and, consequently, which vector corresponds to the "direction" the creature/player is facing.

The short answer

By default, our engine follows the convention that "up" is in +Y axis.

This is consistent with X3D. And exporters from 3D authoring software are ready for this — e.g. Blender X3D exporter by default rotates models to change +Z axis (traditional "up" vector in Blender) to the +Y axis. So things just work.

How to use Blender with up = Y or Z conventions

  • If you want to follow "+Y axis is up" convention (easier, i.e. you don't really need to do anything):

    1. When exporting from Blender (levels, creatures etc.), let it rotate the model, i.e. change +Z to +Y. This is the default behavior of the X3D exporter. You can verify that it happens by checking in the exporter settings that:

      • Forward = Z Forward
      • Up = Y Up
    2. Make sure the Viewpoint node in X3D (default camera) indicates +Y as the up vector. This is the default X3D value. You can always just remove the Blender's camera and setup the default camera position by code.

      You can also set the viewpoint using the view3dscene feature "Console -> Print Current Camera (Viewpoint)". Paste the generated Viewpoint code into your X3D file (or into an X3D "wrapper" file, that includes another X3D using the Inline node).

    3. Leave TCastleTransform.DefaultOrientation at the default value: otUpYDirectionMinusZ.

  • If you want to follow "+Z axis is up" convention:

    1. When exporting from Blender (levels, creatures etc.), always select to not rotate the model, i.e. keep Blender's original coordinate system. To do this, set in the exporter settings:

      • Forward = Y Forward
      • Up = Z Up
    2. Make sure you use view3dscene (or other VRML/X3D editor) to generate a Viewpoint in your level that makes gravity working in the Z axis.

      You can set the viewpoint using the view3dscene feature "Console -> Print Current Camera (Viewpoint)", just make sure to set earlier the "Navigation -> Walk and Fly Settings -> Change Gravity Up Vector" to 0 0 1.

    3. Set TCastleTransform.DefaultOrientation := otUpZDirectionMinusY.

Detailed discussion about the issue

There are two common conventions:

  1. Most 3D modeling software, like Blender, prefers the up direction to be +Z, and direction to be +X. This is usually sensible when you think about a flat level, with XY representing the map view, and additional Z adding the height.
  2. On the other hand, VRML/X3D and default OpenGL camera prefers the up to be +Y, and direction to be -Z. This makes sense if you think about the screen as being the XY plane, so then if you look straight (in the right-hand coordinate system) you look in -Z direction.

You can also easily imagine other conventions, as you can really pick any 3D vector as "up", and pick anything orthogonal to it as "direction".

Our engine supports various such conventions, we do not force you to follow any particular one. To make things work smoothly, you want to keep the same conventions throughout your process — be wary of this when creating TCastleTransform instances in the engine, when exporting 3D models from Blender, when setting viewpoint (with gravity) in whatever way etc.

Note that Blender (and other 3D modeling software?) by default rotates models when exporting to X3D, to turn +Z into +Y. On one hand, this means that some things will "just work" (you use +Z convention inside Blender, and you get +Y convention inside VRML/X3D). On the other hand, this may create a little confusion if you manually probe some positions in Blender model and type them in X3D code (or ObjectPascal code using our engine): since Blender rotated the models, we necessarily "see" a different coordinate system than what you see in Blender.

For this reason, you may decide to disable this "rotation on export" feature, and instead decide to work with VRML/X3D files where +Z is "up".

VRML/X3D is flexible in this regard: although the default is to have up in +Y, the specification says that up is +Y transformed by the Viewpoint node transformation, and we honour it. In short, this means that gravity is configurable in VRML/X3D file. You can setup your camera in view3dscene, use "Navigation -> Walk and Fly settings -> Change Up Vector", input any vector you want (like "0 0 1"), then use "Console -> Print Current Camera..." option, and copy-paste the generated code from the console to your VRML/X3D file. This will set a Viewpoint with desired up vector, which will be correctly used by our engine (and other good VRML/X3D browsers actually) for gravity.

The notion of direction/up is used by our engine in two places:

  1. Gravity pulls things (player, items, creatures...) down in the -up vector. We automatically detect this based on the gravity vector of the Viewpoint inside your TCastleSceneManager.MainScene (you usually want to set this to your level 3D model). This means that we follow VRML/X3D specification, and gravity vector is derived from the 3D model of your level. You can use e.g. view3dscene to generate Viewpoint node with a desired gravity vector. You can read this vector by looking at TCastleSceneManager.GravityUp, TCastleSceneManager.Camera.GravityUp, and World.GravityUp (from any TCastleTransform code), these are all equal.

  2. If you use TCastleTransform.Direction and TCastleTransform.Up properties to rotate your models (which is the most natural way to transform creatures, player, and items) then they need to know what is your default orientation. That is, how does the model look like when rotation is at zero.

    You configure this using the TCastleTransform.Orientation property.

Usually, you want to just set TCastleTransform.DefaultOrientation, and then it will be used for all your models.