Classes overview (cheatsheet)

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.


  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.


OpenGL context: TCastleWindow / TCastleControl classes

How to use: Just create, or drop on Lazarus form, an instance of this class. Advanced: you can also make your own class providing a non-abstract TUIContainer.

Properties: a Controls list, that contains instances of TUIControl.

2D control: TUIControl class

Important descendants:

How to use: Just create, or drop on form, instances of these class. Then call Window.Controls.Add(...).

Except you usually don't have to create 1st TCastleSceneManager instance: TCastleWindow and TCastleControl already contain a TGameSceneManager instance, automatically created and available inside their Controls list and inside their SceneManager property. You can use TCastleWindowCustom / TCastleControlCustom to avoid this automatic scene manager — useful if you want to use your custom descendant (that overrides some virtual methods) of TCastleSceneManager or TGameSceneManager.

Game world knowledge: TCastleSceneManager

TCastleSceneManager.Camera refers to exactly one instance of:

Camera handling viewpoint and keys: TCamera

Important descendants:

How to use: you can create camera instance (or drop on form), and then assign to TCastleSceneManager.Camera (or TCastleViewport.Camera). You can just let the automatic creation of camera happen, during the nearest rendering or at SceneManager.RequiredCamera, SceneManager.WalkCamera, SceneManager.ExamineCamera call.

TCastleSceneManager.Items is an instance of:

Transformation and grouping of objects: TCastleTransform

This groups and transforms children, that may be:

  • More TCastleTransform — a transformed group of objects,
  • 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 (or drop on form) instances of these classes, as usual. After creation you usually add them to CastleSceneManager.Items (or to some another list e.g. you can add List1: TCastleTransform to CastleSceneManager.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?

Note that most of the actual rendering is eventually done by TCastleScene. The TCastleScene rendering is so versatile that we use it for everything. So treat everything other than TCastleScene as just a way to organize (group, transform) your 3D data.

TCastleTransform is also a base for some optional game-specific classes listed below. More about them later, some of them should be instantiated in a special way:

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


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 TCastleSceneManager.Items.

How to use: To load a game level, you can simply create TCastleScene instance, add it to CastleSceneManager.Items, and set it as CastleSceneManager.MainScene. Alternatively you can use the TGameSceneManager.LoadLevel method, usually like this:

// the 2nd line is a shortcut for
// SceneManager.LoadLevel(Levels.FindName('myLevelName'));

This will create TCastleScene, update CastleSceneManager.Items, CastleSceneManager.MainScene, and do some other stuff helpful for typical 3D games, like handle placeholders — see TGameSceneManager.LoadLevel docs.

Global Resources list contains instances of:


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

  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 T3D:


Creature has Resource property that refers to TCreatureResource.

Important descendants:

How to use: When you load level using TGameSceneManager.LoadLevel, 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

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

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 TGameSceneManager.LoadLevel methods will then take care of loading resources when necessary.


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


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.


Has a list Inventory of instances of TInventoryItem

How to use: just create an instance of TPlayer, and add it to SceneManager.Items, like all normal T3D descendants. You will also almost always want to set this as SceneManager.Player, to make it a central player (connected with central camera etc.).