5. Simple loading of 3D models

We will now load a 3D model from file using the TCastleScene class, and display it. This is one approach to load a simple 3D game level (you will see a better way later to load a game level that integrates with items and creatures out-of-the-box).

Note that this 3D model doesn't have to be static — it can already include animated stuff, interactions, 3D sounds, scripts, and such. VRML / X3D is really quite powerful.

A sample 3D model may be found inside engine examples, in examples/3d_rendering_processing/models/bridge_final.x3dv. You can also download our demo VRML/X3D models.

If you want to make your own 3D model, go ahead — generally use any 3D modeler and export to any 3D format we can handle, preferably X3D. See our guide to creating game data for more information about preparing 3D data.

  1. If you use Lazarus form with TCastleControl: To load a 3D model, double click to create an event OnOpen on TCastleControl, and put there the following code:

    // also add to your uses clauses these units: CastleSceneCore, CastleScene;
     
    procedure TForm1.CastleControl1Open(Sender: TObject);
    var
      Scene: TCastleScene;
    begin
      Scene := TCastleScene.Create(Application);
      Scene.Load('my_scene.x3d');
      Scene.Spatial := [ssRendering, ssDynamicCollisions];
      Scene.ProcessEvents := true;
     
      CastleControl1.SceneManager.Items.Add(Scene);
      CastleControl1.SceneManager.MainScene := Scene;
    end;
  2. If you use TCastleWindow: To load a 3D model, change your program code to this:

    uses CastleWindow, CastleSceneCore, CastleScene;
    var
      Window: TCastleWindow;
      Scene: TCastleScene;
    begin
      Scene := TCastleScene.Create(Application);
      Scene.Load('my_scene.x3d');
      Scene.Spatial := [ssRendering, ssDynamicCollisions];
      Scene.ProcessEvents := true;
     
      Window := TCastleWindow.Create(Application);
      Window.SceneManager.Items.Add(Scene);
      Window.SceneManager.MainScene := Scene;
     
      Window.Open;
      Application.Run;
    end.

At the beginning we create a new instance of TCastleScene, and load it's contents from a file. Scene.Spatial determines what spatial structures (octrees for now) are created, the value [ssRendering, ssDynamicCollisions] is the most flexible one (it allows to speed up the rendering by frustum culling, detect collisions between player and level, and it adapts to a dynamic level that may have some animated parts). Scene.ProcessEvents activates animating VRML/X3D models (you can remove it if you know that your level is, and always will be, static).

The level is added to the scene manager. The level is also set as the MainScene of scene manager, this means that some central settings (like initial camera position, initial headlight status and such) can be obtained from this scene.

What is a "Scene Manager"?

Scene manager contains the whole knowlegle about your game 3D world. It is essential to add all your 3D stuff to a scene manager. An instance of scene manager (class TCastleSceneManager) is already created and available in the SceneManager property of the TCastleControl or TCastleWindow instance.

By default TCastleSceneManager also acts as a viewport filling the whole window. So the whole OpenGL context is filled to show your 3D world. In more complex scenarios you can have many smaller viewports inside your window using TCastleViewport (see custom viewports notes, and examples/3d_rendering_processing/multiple_viewports.lpr and examples/fps_game/fps_game.lpr examples). You can also turn off scene manager from being a viewport (setting TCastleSceneManager.DefaultViewport to false), and then scene manager is really only something that keeps track of 3D world, and nothing more.

In more advanced scenarios you may need to create and manage scene manager yourself. There are special classes available (TCastleControlCustom or TCastleWindowCustom) that allow you to use your own scene manager instance (or maybe zero, or maybe more than one scene manager instance, maybe a custom scene manager class...).