Editor

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 bin subdirectory.

1. Video Introduction

2. Create, build, run projects

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

3. Design user interfaces and 3D/2D transformation hierarchies

You can visually design:

  1. 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).

    Saved as xxx.castle-user-interface files (somewhere in the data/ subdirectory).

    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.

  2. A hierachy of 3D / 2D scenes and transformations. Anything descending from TCastleTransform.

    Saved as xxx.castle-transform files (somewhere in the data/ subdirectory).

    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.

  3. A hierachy of non-visual classes (really anything descending from TComponent although we advise to descend from our extended TCastleComponent).

    Saved as xxx.castle-component files (somewhere in the data/ subdirectory).

    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;

The xxx.castle-user-interface, xxx.castle-transform, 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.

4. Edit source code

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.

Code Editor Preferences

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.

5. File browser

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 castle-engine-output directory.

  • 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-user-interface, xxx.castle-transform, 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:

    • On 3D and 2D models we run view3dscene.

    • On images we run castle-view-image.

    • On Pascal files we run Lazarus (see above).

    • Design files are opened in the current editor.

    • On other files, we run the default system application for 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.

6. Custom (project-specific) components in the visual designer

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:

  1. In the 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');

    The RegisterSerializableComponen is in the CastleComponentSerialize unit, so make sure it is in the uses clause.

  2. 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 editor_units="MyButtonUnit, MyMenuUnit".

  3. Make sure:

    1. Lazarus location is correctly set in the editor "Preferences" window. Alternatively you could adjust $PATH (make sure we can find lazbuild from Lazarus).

    2. 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 $CASTLE_ENGINE_PATH).

  4. 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: castle-engine editor.

    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)".

See advanced_editor/custom_component as an example that defines and registers TImageGrid component in the GameControls unit.

More documentation about implementing custom components is here.