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
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
that is accessed from code using the
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 TUIState.DesignUrl (see almost any engine example or "New Project" template). Other approaches are possible too, e.g. you can load using UserInterfaceLoad,
TSerializedComponent.UserInterfaceLoad and more. See examples like advanced_editor/advanced_loading_designs.
A hierachy of 3D / 2D scenes and transformations. Anything descending from TCastleTransform.
xxx.castle-transform files (somewhere in the
You can load it in your game using TransformLoad and insert into existing hierarchy of
TCastleViewport.Items. You can also use TCastleTransformDesign to use it in other designs (thus having a reusable composition of 3D/2D objects). See examples like advanced_editor/advanced_loading_designs.
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.
Open various example projects to see the editor, with various components, in action. We recommend trying out various templates (create "New Project" in editor), examples/component_gallery, examples/tiled/strategy_game_demo.
The editor integrates with Lazarus to edit Pascal code.
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.
We use Lazarus by default as it features code-completion that understands Pascal syntax perfectly, integrated debugger and more. We also automatically set up Lazarus project files, so that you can press Run from Lazarus, and it will build (and run, debug) your project (for the current system).
Note: If you're bothered by the default multiple-windows UI of Lazarus, install in Lazarus package
components/anchordocking/design/anchordockingdsgn.lpk (you will find this in Lazarus source code). It will recompile Lazarus and give you an IDE with docked windows.
Note: Instead of Lazarus, you can use any text editor to edit Pascal files. Visual Studio Code, Atom, Emacs... 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. See here for details.
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.
Drag files from the "Files" area onto the
TCastleViewport instance in a visual designer. This automatically creates a
TCastleScene with the given scene loaded.
Projects may define custom components (any descendant of TComponent; usual classes to derive your components from include TCastleUserInterface, TCastleTransform, TCastleBehavior, TCastleComponent). It is possible to include your custom components within the Castle Game Engine Editor, so that they can be added and configured at design-time, just like standard CGE components. To do this:
initialization section of some unit (it is usually the same unit where you define your custom component), register it by calling something like this:
RegisterSerializableComponent(TMyButton, 'My Button');
RegisterSerializableComponen is in the
CastleComponentSerialize unit, so make sure it is in the uses clause.
Inside your CastleEngineManifest.xml, set the attribute
editor_units to list all the units that call the
RegisterSerializableComponent. It is a comma-separated list, like
Lazarus location is correctly set in the editor "Preferences" window. Alternatively you could adjust
$PATH (make sure we can find
lazbuild from Lazarus).
Make sure the CGE location is correctly set. It should be detected automatically if you use the engine package (but you can always customize it using the environment variable
Use menu item "Project -> Restart Editor (With Custom Components)" in the editor (once you open a project).
Alternatively, use the command-line build tool command:
Both ways will rebuild and run a customized version of the editor that includes your custom components.
You can confirm you are running an editor with custom components by looking at the window title, it should include "(With Custom Components)".
Copyright Michalis Kamburelis and other Castle Game Engine developers.
Thank you to Paweł Wojciechowicz from Cat-astrophe Games for various graphics.
This documentation is also open-source and you can even redistribute it on open-source terms.