22. Classes overview (cheatsheet)
This final tutorial page 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.
- OpenGL context:
How to use: Just create, or drop on Lazarus form,
an instance of this class.
Advanced: you can also make your own class implementing
Properties: a Controls list, that contains instances of
- 2D control: TUIControl class
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
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.
- 3D world knowledge: TCastleSceneManager
TCastleSceneManager.Camera refers to exactly one instance of:
- Camera handling viewpoint and keys: TCamera
How to use: you can create camera instance (or drop on form),
and then assign to TCastleSceneManager.Camera (or TCastleViewport.Camera).
You can also do nothing, and let the automatic creation of camera
happen at the nearest rendering (more precisely, at ApplyProjection).
It will create a camera using
TCastleSceneManager.CreateDefaultCamera and assign it to TCastleSceneManager.Camera property.
TCastleSceneManager.Items is a list of:
- 3D object: T3D
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: T3DList to
and then add Scene: TCastleScene to List1.)
It's your decision how (and if at all) you need to build a hierarchy
of 3D 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.
Although all T3D classes have the possibility to render something
by overriding the T3D.Render method, but this feature is
not used (much) by existing engine classes.
That's because 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.
Exceptions to the above: usage of TPlayer,
TItemOnWorld is a little special,
more about them later.
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
Alternatively you can use the TGameSceneManager.LoadLevel method, usually like this:
// the 2nd line is a shortcut for
This will create TCastleScene, update
and do some other stuff helpful for typical
3D games, like handle placeholders — see
Global Resources list contains instances of:
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 := 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
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
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
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
Has TItemOnWorld.Item property that refers to one instance of:
This in turn has
TInventoryItem.Resource property that refers to TItemResource
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
to make it a central player (connected with central camera etc.).