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.
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
How to use: Just create instances of these classes.
Add them to the container, by calling
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.Navigation refers to one (or none) instance of:
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
TCastleViewport.Items is an instance of:
This groups and transforms children, that may be:
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
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?
TCastleViewport.Items.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 TCastleViewport.Items.
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:
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 TCastleTransform:
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
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 TLevel.Load methods will then take care of loading resources
Has TItemOnWorld.Item property that refers to one instance of:
CasRes+ item resource name.
Copyright Michalis Kamburelis and other Castle Game Engine developers.
Thank you to Paweł Wojciechowicz from Cat-astrophe Games for various graphics.
This documentation is also open-source and you can even redistribute it on open-source terms.