Castle Game Engine Editor is the most important visual tool of our engine. It allows to create, edit and build applications with CGE. Get it by downlading latest Castle Game Engine release and run
castle-editor executable in the
You can create a project (using a number of templates) or open an existing one. You can compile, run and package the project using the Run menu.
A Castle Game Engine project is a directory containing the CastleEngineManifest.xml file. Most often it also contains a subdirectory
data/ that is accessed from code using the castle-data:/xxx URLs. Everything else is up to you, organize your source code and data however you like.
Note that compiling and packaging a project can also be done using the command-line CGE build tool. Actually, the editor just calls the build tool under the hood. The build tool in turn calls a compiler (FPC) and some other tools (e.g. Android-specific packaging tools).
You can visually design:
A hierarchy of user-interface controls. Anything descending from
TCastleUserInterface, like a button, label, or a powerful viewport (that contains a hierarchy of 3D / 2D scenes and transformations inside).
xxx.castle-user-interface files (somewhere in the
They are typically loaded in your application by setting the
TCastleView.DesignUrl (see almost any engine example or "New Project" template). Other approaches are possible too, e.g. you can load using
TSerializedComponent.UserInterfaceLoad and more. See examples like advanced_editor/advanced_loading_designs.
A hierachy of 3D / 2D scenes and transformations. Anything descending from
xxx.castle-transform files (somewhere in the
xxx.castle-component files (somewhere in the
You can load it in your game using
ComponentLoad. Do whatever you want with the resulting components. You can find the named components in your design using the
FindRequiredComponent method, like this:
var ComponentRoot, ComponentOwner: TComponent; MySound: TCastleSound; MyFont: TCastleFont; begin ComponentOwner := TComponent.Create(Application); ComponentRoot := ComponentLoad(\'castle-data:/my_design.castle-component\', ComponentOwner); MySound := ComponentOwner.FindRequiredComponent(\'MySound\') as TCastleSound; MyFont := ComponentOwner.FindRequiredComponent(\'MyFont\') as TCastleFont; end;
xxx.castle-component are simple JSON text files. You should commit them to the version control, just like your source code. You can have as many such files inside your project as you need to.
Let us emphasize that when using the editor, you still code using the same CGE API as described throughout this manual. At any point you can load an instance of a component from a designed file and use it as you wish.
The editor integrates with various Pascal code editors:
You can use Lazarus to edit Pascal code.
You can use Delphi IDE.
You can use VS Code.
Or really any other text editor. We advise looking for full-featured editor, with features like Pascal syntax highlighting, code completion and integrated debugger. In CGE editor, go to "Preferences → Code Editor" to configure your custom editor, so it is run when you e.g. double-click on Pascal files from the editor or use various other "Code" menu features.
To edit the Pascal unit you have various options:
In CGE editor: enter the
code/ subdirectory, and double-click on a Pascal unit.
In CGE editor: use menu item "Code → Edit Unit …".
In CGE editor: press F12 when some design is open. This will open the associated unit.
In Lazarus: open the project in Lazarus, and open units from Lazarus then. All Pascal files found on the search path are automatically part of the LPI project, they are visible in Project Inspector in Lazarus.
In Delphi: open the project in Delphi, and open units from Delphi then.
The CGE editor automatically sets up Lazarus and Delphi project files, so that you can easily compile and run from these IDEs.
You can browse the application files. Our "Files" browser at the bottom just displays the files inside your project directory. It merely hides some known unimportant things, like temporary
Note that the
data/ subdirectory is somewhat special. It is automatically detected, it is automatically packaged (e.g. in Android apk), and it can always be accessed by castle-data:/xxx URL. You will place there 3D models, 2D images, designs (
xxx.castle-component files) and everything else you load in the game.
It is somewhat equivalent to Unity
Assets/ subdirectory. See Castle Game Engine for Unity developers for more pointers, if you come with knowledge about Unity.
Note that your Pascal source code should be outside the
data/ subdirectory. Your source code can be anywhere within the project, we don’t have any strict requirement here, although we recommend
code/ subdirectory and the compiler is set to search it by default. Remember to list any new code subdirectory in
<search_paths> in CastleEngineManifest.xml file (for now, just edit this file in any text editor; in the future CGE editor can allow to edit it through a GUI dialog).
Double-clicking on various files runs a tool suitable to preview/edit them:
Scenes, images and audio files have a preview window once you select them in the Files panel. You can even quickly listen to audio files this way.
You can drag files from the "Files" area onto the design.
Drag 3D and 2D models (like glTF or Spine or X3D files) on
TCastleViewport to automatically create a
TCastleScene with the given scene loaded.
Drag audio files on
TCastleViewport to automatically create sound source (TCastleSoundSource and TCastleSound).
Drag images on
TCastleViewport to automatically create
Drag UI designs (*.castle-user-interface) to automatically create
TCastleDesign that refers to them.
Drag transform designs (*.castle-transform) to automatically create
TCastleTransformDesign that refers to them.
Drag images on user interface (not viewport) to automatically create
TCastleImageControl. If you want to force creating 2D
TCastleImageControl even when you drop on viewport, hold Shift when dropping.
You can register your own components to use them within CGE editor. This is a powerful mechanism to define e.g. your own user interface elements. See the documentation about custom components.