Big documentation update – new manual, with tutorial, about using viewports and scenes (from editor and from code)

Posted on

Viewport with cars in Castle Game Engine editor

Our documentation about viewports and scenes (one of the most important concepts in Castle Game Engine) got a big update! I wrote new pages documenting how to use the editor to setup 3D and 2D worlds, and how to use Pascal API with latest features and best practices. This is a “must read” for everyone using Castle Game Engine!


  1. It starts with introduction to our concepts – viewport, scenes, transformations, camera, navigation.

  2. Then a large new tutorial-like chapter that walks you through setting up viewport and scenes in the editor to make 3D environment.

  3. New chapter covering 2D information, in particular important features of the orthographic camera.

  4. Camera and Navigation chapters describe controlling the camera (“what do you see”) and navigation (“how to react to user input to change camera”).

  5. Writing code to modify scenes and transformations talks about how to access everything from Pascal code, how to react to user input, how to animate things by code etc. This is partially based on the old documentation, but heavily updated to talk how the code plays together with states, editor and generally how it should be done in latest CGE versions. Almost all text was redone to be simpler and reflecting current best practices.

  6. Finally, a short section about using multiple TCastleViewport instances to share the same world.

Various other documentation updates were done:

  1. Installation and Build your first application have been split into 2 separate chapters, and updated to document that you can use Delphi as an alternative to FPC/Lazarus.

  2. OpenAL chapter was refreshed (lots of old outdated content was just removed).

  3. Order of chapters in the manual has changed, to put the most important things at the top.

Of course there are still unfinished things. This is not the end of documentation work ๐Ÿ™‚ In particular:

  1. I’m not yet happy with bottom sections of Writing code to modify scenes and transformations, about

    1. (edit: this was fixed the same day as this news) “Building and editing the scene” (they need a better example, simpler and more useful — how to define a mesh; right now they show instead a quite convoluted code to build 2 boxes, which isn’t impressive at all, you can do it already much simpler using TCastleBox, or just without using any code at all – you can do it in editor, you can do it in Blender)

    2. (edit: this was fixed the same day as this news) “Behaviors” (we need a longer explanation and example there). I have ideas for both of these, and will probably do it this weekend.

  2. User interface chapter needs an upgrade, to describe editor, states and all the latest features. It correct right now, but sometimes describing an old approach to doing things, instead of new advised workflows. (hint: the Designing user interface and handling events (press, update) within the state chapter is up-to-date and good, so follow this first!)

  3. Manual about text should also be updated to show usage of TCastleFont and editor more. Following new features announced here.

And also new functionalities will come soon. When reading 3D tutorial it is obvious we should improve how cameras work, and add lights to the editor. So this chapter will be simpler, when we make some details more intuitive in the editor ๐Ÿ™‚ I want to address both things very soon, as I announced in my plan for 2022.

Start the discussion at Castle Game Engine Forum