Viewport with scenes, camera, navigation

Viewport with 3D design

1. Viewport and scenes

1.1. Overview

The most important Castle Game Engine class to display 3D and 2D assets is TCastleScene. You simply set the TCastleScene.URL property to load an asset, like gltf or sprite sheet file.

You have to insert instances of scenes into a viewport (more precisely, TCastleViewport.Items tree) to make them actually visible. TCastleViewport represents a 2D viewport on a screen, within this viewport your world (3D or 2D) is displayed. Viewport is a user interface control, which means that it descends from TCastleUserInterface and it shares the same feature we’ve seen in the previous chapter about states and UI.

The scenes can be transformed (moved, rotated, scaled) within the viewport. You can arrange them in transformation groups using TCastleTransform. TCastleTransform is an ancestor of TCastleScene that doesn’t display anything by itself, but it transforms all the children.

1.2. Viewport.Items, TCastleTransform descendants

TCastleViewport has a property TCastleViewport.Items that holds everything that the viewport displays.

You can add there any classes descending from TCastleTransform. This includes:

  • Just the TCastleTransform instance. While it doesn’t display anything, but it transforms (move, rotates, scales) the children.

  • TCastleScene instance. As said above, this is your important class to display 3D and 2D assets. It can render, animate, perform collisions etc.

  • TCastleText instance allows to display a text, possibly transformed in 3D. The font is also configurable, using TCastleText.CustomFont. In many ways, the TCastleText an analogy to TCastleLabel. Use TCastleLabel for user interface, use TCastleText when the text is conceptually part of the game world, may be in 3D, and is attached to some place in your game world.

  • TCastlePlane, TCastleBox, TCastleSphere, TCastleCylinder, TCastleCone are easy 3D "primitives" that you can use to design your world. All of them have a configurable size, material, texture and other basics. While you could create such simple objects in any 3D authoring software (and use them through TCastleScene as well), our primitives are often very useful for quickly prototyping your game world.

2. Camera

Camera determines what part of the world (3D or 2D) is visible in the viewport. Ready camera instance is available as TCastleViewport.Camera property. You can configure camera easily by changing its properties e.g. MyViewport.Camera.Position := Vector3(1, 2, 3).

3. Navigation

Navigation is our term to describe a class handling user input to move the camera. Our engine provides some ready navigation classes, for example TCastleWalkNavigation implementing a typical navigation in FPS games. But you don’t have to use our ready navigation classes, you can easily just move the camera with your own code.

4. Next: Using the viewport in Castle Game Engine editor

Now that you know the basic terminology and classes, let’s see how to actually use them.

Next chapters will start by describing how to use them in our visual editor, and later we’ll show examples how to use them from Pascal. Remember that everything you do inside the editor can be done by Pascal code too. In particular, all the classes and their properties that you use within the editor are really the same classes you use from Pascal code. So whatever you can change from editor — you can also later change during the game, from code. And all the class instances that you create within the editor (like TCastleScene) — can also be created (or destroyed) in any order during the game execution.

To improve this documentation just edit the source of this page in AsciiDoctor (simple wiki-like syntax) and create a pull request to Castle Game Engine WWW (cge-www) repository.