Castle Game Engine
← Users Developers →
 
Intro
 
News
 
view3dscene
 
The Castle
 
All Programs
 
Forum
 
Donate
 
Engine
 
VRML/X3D
 
Blender
 

23. 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.

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.

Classes:

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 implementing IUIContainer interface.

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.

3D 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 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

Important descendants:

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 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 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, TCreature, TItemOnWorld is a little special, more about them later.

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

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

TCreature

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

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 TGameSceneManager.LoadLevel 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 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.).