Classes overview (cheatsheet)

1. Introduction

This manual chapter summarizes information about the most important classes and concepts of our engine. It can be treated like a cheatsheet, concise description of engine architecture.

Notes:

  1. We list "Important descendants" for many classes below. Remember you are not limited to the listed classes. You can define (and "register" or such when necessary) your own descendants of all existing engine classes. We tried hard to make the engine really flexible and possible to customize at various levels.

  2. For more details about every class, see API reference, in particular class hierarchy.

2. Engine core classes

Container: TCastleWindowBase, TCastleControlBase classes

You need to have a container to display anything using CGE, and allow user to interact with your application. The "container" has an OpenGL rendering context, and handles user input in a cross-platform way. A usual application creates exactly one instance of TCastleWindowBase or TCastleControlBase, and uses this instance for the entire game.

How to use: You can explicitly create an instance of this class.

In case of TCastleControlBase, you can also drag-and-drop it on a Lazarus form using Lazarus form designer.

Most important properties: a Controls list, that contains instances of TCastleUserInterface.

User interface control: TCastleUserInterface class

Important descendants:

How to use: Just create instances of these classes. Add them to the container, by calling Window.Controls.InsertFront(...).

You can also design user interface using CGE editor. In this case you can load (instantiate) it using UserInterfaceLoad or TUIState.InsertUserInterface.

Viewport: TCastleViewport

Viewport allows to display TCastleScene. You can arrange scenes into groups and transform them using TCastleTransform. TCastleScene is the only way to display 3D objects using CGE, it is also advised way to display 2D game assets (see about 2D games here).

TCastleViewport.Camera refers to exactly one instance of TCastleCamera.

TCastleViewport.Navigation refers to one (or none) instance of:

Navigation handling keys and mouse: TCastleNavigation

Important descendants:

How to use: you can create navigation instance, and then assign to TCastleViewport.Navigation. Or you can set Viewport.AutoNavigation := true and let the automatic creation of navigation happen during the nearest rendering. Or you can force creating a suitable navigation by calling Viewport.RequiredNavigation, Viewport.WalkNavigation, Viewport.ExamineNavigation call.

TCastleViewport.Items is an instance of:

Transformation: TCastleTransform

This groups and transforms children, that may be:

  • More instances of TCastleTransform,
  • TCastleScene — a 3D or 2D model, that can be rendered, animated, checked for collisions and so on. This is a descendant of TCastleTransform, so it can be directly transformed and it can have children too.

How to use: you can create instances of these classes, as usual. After creation you usually add them to TCastleViewport.Items (or to some another list e.g. you can add List1: TCastleTransform to TCastleViewport.Items, and then add Scene: TCastleScene to List1.) It's your decision how (and if at all) you need to build a hierarchy of objects using lists and transformations. Maybe it's enough to just load your whole 3D model as a single TCastleScene?

TCastleViewport.Items.MainScene refers to one (or none) instance of:

TCastleScene

The main scene is used to detect initial background, initial viewpoint, initial navigation mode and so on — information that naturally has only a single value for the entire 3D world. In VRML/X3D, these concepts are called "bindable nodes" — of course they can change during the lifetime of the world, but at a given time only one value is active.

The main scene should also be present in TCastleViewport.Items.

How to use: To load a game level, you can simply create TCastleScene instance, add it to CastleViewport.Items, and set it as TCastleViewport.Items.MainScene.

3. Utilities for typical 3D games

As explained in the Utilities for typical 3D games -> Overview, our engine contains a number of optional classes helpful to implement typical 3D games. Their usage is more limited than the "core" classes listed above.

TCastleTransform is a base for the classes listed below. More about them later, some of them should be instantiated in a special way:

Global Resources list contains instances of:

T3DResource

Important descendants:

How to use: Put resource.xml files in your game's data directory. Call Resources.LoadFromFiles at the beginning of your game to create T3DResource instances and add them to Resources list.

Optionally: If you need to have the instances available in ObjectPascal code, you can get them like

var
  Sword: TItemWeaponResource;
...
  Sword := Resources.FindName('Sword') as TItemWeaponResource;

You refer to each creature/item resource by it's unique name, so in this example you expect that some resource.xml will have name="Sword" inside.

Optionally: you can define your own descendants of T3DResource classes. To make them recognized, call

RegisterResourceClass(TItemMeleeWeaponResource, 'MeleeWeapon');

before doing Resources.LoadFromFiles. This allows you to use own type, for example type="MeleeWeapon", in resource.xml files for items. Many items may use the same type.

See creating resources for more details.

Optionally: it's actually possible to create T3DResource instances by pure ObjectPascal code, and add them to Resources list manually, without resource.xml files. But usually that's not comfortable.

Special descendants of TCastleTransform:

TCreature

Creature has Resource property that refers to TCreatureResource.

Important descendants:

How to use: When you load level using TLevel.Load, instances of initial creatures/items existing on level are automatically created for you, replacing the placeholder objects in 3D file. Just add in Blender 3D object (with any mesh, geometry doesn't matter, I usually use wireframe cubes) and name it CasRes + resource name, like CasResKnight. CasRes is short for Castle Game Engine Resource.

From code, you can also create creatures dynamically, by calling TCreatureResource.CreateCreature. For example

var
  Alien: TCreatureResource;
...
  Alien := Resources.FindName('Alien') as TCreatureResource;
...
  Alien.CreateCreature(...);

This is a good way to dynamically make creatures spawn in the 3D world (e.g. maybe you make an ambush, or maybe you want to create a "rush" when monsters attack in waves, or maybe you want to make a crowd...). Make sure that all necessary creatures are declared in level's index.xml file under <prepare_resources>, to prepare creatures at level loading (you don't want to cause a sudden delay in the middle of the game). T3DResource and TLevel.Load methods will then take care of loading resources when necessary.

TItemOnWorld

Has TItemOnWorld.Item property that refers to one instance of:

TInventoryItem

This in turn has TInventoryItem.Resource property that refers to TItemResource

Important descendants:

How to use: similar to creatures, see notes above. Items are very similar, except TInventoryItem is not a 3D object (it cannot be directly added to the level), only TItemOnWorld is a 3D object.

TPlayer

Has a list Inventory of instances of TInventoryItem

How to use: just create an instance of TPlayer, and set it as Level.Player.