Engine on a form (VCL, FMX, LCL) using TCastleControl

Table of Contents

1. Introduction
2. Delphi installation
- 2.1. Screenshots
3. Lazarus installation
- 3.1. Screenshots
4. Opening the project in CGE editor
5. Initializing the resources
6. Loading user interface and view
7. Focus (receiving key input)
8. Comparison between TCastleWindow and TCastleControl
- 8.1. It is not allowed to use both TCastleWindow and TCastleControl in a single application

1. Introduction

TCastleControl is a component you can drop on a form. It allows to do all CGE rendering and processing as part of a form, and TCastleControl can be surrounded on your form by any other components.

The same component is available for Lazarus (LCL) and Delphi (VCL, FMX) forms.

2. Delphi installation

Install the Delphi packages following the Delphi packages installation instructions.

Make sure to use the menu item "Tools → Castle Game Engine → Configure Delphi to Use Engine" as described on that page, to have CGE units available for all your projects.
Test: Open the examples in examples/delphi, there’s one example for VCL one for FMX.

These are regular Delphi projects, open them in Delphi, compile and run (for Windows 32-bit or 64-bit).

You can also open each example in CGE editor (point the CGE editor to the CastleEngineManifest.xml file inside the example directory), to edit the 3D / 2D / UI designs there.

2.1. Screenshots

3. Lazarus installation

Warning

We’re in the middle of rename now. The castle_components.lpk will soon be renamed to castle_engine_lcl.lpk.

Install in Lazarus the package castle_components.lpk. In the package dialog, use the option to "Install" (under the "Use" button).

Note: Installing the castle_components package will also automatically install the package castle_base, as a dependency. That’s good.

Once castle_components.lpk is successfully installed, Lazarus restarts, and you should see the "Castle" tab with our components.
To test, open in Lazarus examples in examples/lazarus/. Like examples/lazarus/model_3d_viewer.
To use in your own application:
1. Create a normal new LCL project (using Lazarus "New Project" menu item). Choose "Application".
2. Pick TCastleControl from the component palette (tab "Castle") and drop it on a regular Lazarus form.
3. Done. Press "Run" :)

3.1. Screenshots

4. Opening the project in CGE editor

While you will use Delphi / Lazarus to design your forms, it is also useful to design CGE components using CGE editor. To do this, create a CastleEngineManifest.xml file within your project.

This is an example for Delphi application:

<?xml version="1.0" encoding="utf-8"?>
<project name="my_project"
  standalone_source="my_project.dpr"
  compiler="delphi"
>
</project>

Note	Delphi uses can just open the project in Delphi IDE, and use from Delphi the menu item "Tools → Castle Game Engine → Open in CGE editor". This will automatically create a manifest file, just like shown above, if it is missing.

This is an example for Lazarus application:

<?xml version="1.0" encoding="utf-8"?>
<project name="my_project"
  lazarus_project="my_project.lpi"
  build_using_lazbuild="true"
>
</project>

This way you can open this project in the CGE editor and:

open and modify CGE designs, like xxx.castle-user-interface files,
run the project from CGE editor (CGE editor, and build tool, will just invoke Delphi compiler or lazbuild under the hood).

5. Initializing the resources

Essentially, you can initialize your game resources at any time. Even before any TCastleControl exists. For example in the OnCreate event of a main form. All Castle Game Engine components can be created and configured regardless of the OpenGL context existence.

6. Loading user interface and view

In the simple case, you can load a design (file xxx.castle-user-interface) using TCastleControlContainer.DesignUrl, and access loaded components using TCastleControlContainer.DesignedComponent.

In more involved cases, you should use multiple views within your control. In this case, use TCastleView within the TCastleControl, and load a design (file xxx.castle-user-interface) inside the view using TCastleView.DesignUrl. This is analogous to our recommended workflow with TCastleWindow. You can add new view using CGE editor ("Code → New Unit → View…"), or just define a new unit like this:

unit GameViewMain;

interface

uses CastleUIControls;

type
  TViewMain = class(TCastleView)
  published
    { Components designed using CGE editor.
      These fields will be automatically initialized at Start. }
    // ButtonXxx: TCastleButton;
  public
    constructor Create(AOwner: TComponent); override;
    procedure Start; override;
  end;

var
  ViewMain: TViewMain;

implementation

constructor TViewMain.Create(AOwner: TComponent);
begin
  inherited;
  DesignUrl := 'castle-data:/gameviewmain.castle-user-interface';
end;

procedure TViewMain.Start;
begin
  inherited;
end;

end.

That’s enough to load gameviewmain.castle-user-interface design from your data subdirectory.

To initialize this view in your application, you can use this code e.g. in OnCreate form event:

ViewMain := TViewMain.Create(Application);
MyCastleControl.Container.View := ViewMain;

A simple example of using views with TCastleControl is in examples/lazarus/multiple_views. The CGE API used there is the same for Lazarus (LCL) and Delphi (VCL, FMX) versions of TCastleControl.

7. Focus (receiving key input)

Like every LCL / VCL / FMX control, our TCastleControl receives the keys only when it has focus. The control does not capture all the keys pressed over the form (this would be bad, as other controls, maybe even other TCastleControl on the same form, may want to handle them). To make sure that controlling the camera by keys (like AWSD or arrows) works, make sure that your control has a focus.

Note	The advises below were tested with LCL, though they should apply to VCL and FMX too. Report if you encounter difficulties applying them.

To make the control have focus:

You can call MyCastleControl.SetFocus; at any time to explicitly make the MyCastleControl focused. You can assign this to some menu item, or key shortcut handled by form, to allow user to easily switch focus to the TCastleControl instance.
You can also use TCastleControl.AutoFocus to make the control automatically focused when user presses mouse over it.

8. Comparison between TCastleWindow and TCastleControl

Most of this manual describes the process of using the engine with the TCastleWindow instead of TCastleControl. All new projects created from editor templates use TCastleWindow. We generally advise TCastleWindow, as:

TCastleWindow works on all CGE platforms (desktop, mobile - Android, iOS, consoles - Nintendo Switch, upcoming web target). It allows us to have true cross-platform projects, that can be recompiled to any supported platform out-of-the-box.
TCastleWindow allows us to handle events and message loop on the CGE side, and make it efficient. For example, it makes mouse look work perfectly smooth.

On the other hand, using the TCastleControl has one big benefit: as you place the control inside a form, you can surround it with all the standard VCL / FMX / LCL GUI controls. So you can use numerous GUI controls, with native look on all desktop systems, together with Castle Game Engine.

We are committed to supporting both approaches (TCastleControl and TCastleWindow) in the foreseeable future.

8.1. It is not allowed to use both `TCastleWindow` and `TCastleControl` in a single application

You have to make a choice:

Use TCastleWindow. Use the Application singleton from CastleWindow unit to manage these windows.
Use TCastleControl. Use the VCL / FMX / LCL forms, along with VCL / FMX / LCL Application singleton in the Forms unit, to manage your application.

You cannot mix these approaches, as neither VCL / FMX / LCL (in which our TCastleControl works) nor TCastleWindow are prepared to handle the situation that they only handle some application forms, and other library handles the other forms.

That is also why for Lazarus we have separate packages

castle_window.lpk (with TCastleWindow) and
castle_components.lpk (with TCastleControl; a better name would be castle_lcl.lpk).

You should not use both of these packages at the same time.

In case of Delphi, we have only one package, because there’s no reason to put TCastleWindow in a package.

Note that, if you use TCastleControl, it is OK to have multiple TCastleControl instances visible at the same time. Similarly, if you use TCastleWindow, you can have several TCastleWindow instances visible at the same time (but only on desktop platforms), see examples/window/multi_window.

To improve this documentation just edit this page and create a pull request to cge-www repository.