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.
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.
For more details about every class, see API reference, in particular class hierarchy.
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.
Controls list, that contains instances of
false, and using only TCastleViewport for viewports).
How to use: Just create, or drop on form, instances of these class.
Except you usually don't have to create 1st
TCastleWindow and TCastleControl already contain a TGameSceneManager instance,
automatically created and available inside their
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.
TCastleSceneManager.Camera refers to exactly one instance of:
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:
This groups and transforms children, that may be:
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
and then add
Scene: TCastleScene to
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:
Levels.LoadFromFiles(...); SceneManager.LoadLevel('myLevelName'); // 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:
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
Optionally: you can define your own descendants of T3DResource classes. To make them recognized, call
before doing Resources.LoadFromFiles.
This allows you to use own type, for example
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:
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
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
<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
Has TItemOnWorld.Item property that refers to one instance of:
CasRes+ item resource name.
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.).
Copyright Michalis Kamburelis and others. Particular thanks go to Paweł Wojciechowicz from Cat-astrophe Games for various graphics. Even this documentation is open-source and you can redistribute it on open-source terms, in particular CC BY-SA.