We have extended our documentation how to put engine on Lazarus (and soon Delphi too) form. It now discusses also where to initialize CGE in this approach, how to use states and UI, and makes it clear that mixing TCastleControl and TCastleWindow in one application is not allowed.

I advise every CGE developer to run these 2 new examples today! 🙂

1. examples/component_gallery is a 12-page demo of possibilities of user interface components in CGE. Run the demo, and browse the pages to see what is possible. Then explore the demo in the editor (open designs data/page_xxx.castle-user-interface) to see how you can do this.

   The screenshots from this demo also augment new manual page about user interface.

2. examples/viewport_and_scenes/transform_primitives shows possibilities of primitives (sphere, cylinder, cone, sphere, plane, box, text) in the viewport.

   The screenshot from this demo also improves manual about viewport.

We have a new component TCastleImageTransform, which is now the most advised way to place simple image inside a viewport. This is great for static backgrounds in games, backgrounds that move with player, static pieces of 2D levels etc.

So we now have 2 advised (simple, available in editor, full-featured) ways to handle images:

1. TCastleImageControl (if you want image be a UI)

2. TCastleImageTransform (if you want image be inside TCastleViewport, which means it is part of the game world, and it moves along with the rest of the world or with game camera).

New TCastleImageTransform allows to easily e.g.:

• adjust pivot TCastleImageTransform.Pivot – pivot doesn’t have to be in the center, in can be anywhere, e.g. in any corner of the image, whatever is comfortable in your situation.

• repeat the image a number of times using TCastleImageTransform.RepeatImage.

• control the image size by referring to “what size it should pretend to have” instead of only by applying a float scale multiplied by the original size, see TCastleImageTransform.Size.

These features were possible previously too (by using image inside TCastleScene) but now they are more comfortable, exposed as more natural properties.

We’re moving further with Vampyre Imaging Library integration, to have more features related to image loading and at the same time less code to maintain in Castle Game Engine.

1. We now use Vampyre always, by default, with both FPC and Delphi. This makes our code simpler and more consistent.

   Note: our castle_base.lpk depends on Vampyre Lazarus packages, to use Vampyre packages in a clean (Lazarus) way, using all compilation configuration done by Vampyre authors. This is important if you compile using Lazarus (though project LPI file, that in turn uses LPK packages).

   After updating to latest CGE, be sure to use “Preferences -> FPC and Lazarus -> Register Lazarus Packages” in CGE editor,or just open in Lazarus and compile these 2 packages:

   src/vampyre_imaginglib/src/Packages/VampyreImaginePackage.lpk
   src/vampyre_imaginglib/src/Packages/VampyreImaginePackageExt.lpk
   

   This doesn’t matter if you compile using Delphi, or using CGE build tool that executes FPC directly (passing paths to CGE and Vampyre, without relying on Lazarus LPI/LPK information).

2. We now rely on Vampyre for loading and saving of BMP, PPM and RGBE image formats.

   I completely removed the old code for handling these image formats (without Vampyre) in CGE. This means less code in CGE which makes me happy 🙂 Moreover, Vampyre brings some extra features: handles RLE-compressed BMP files, can save RGBE files with compression.

3. We synchronized with latest Vampyre Imaging Library code, and reenabled JP2 and TIFF saving using Vampyre. We check TSingleImage.SaveToStream to know if it’s successful.

4. For now, you can still disable Vampyre usage, by removing {$define USE_VAMPYRE_IMAGING} from our src/common_includes/castleconf.inc.

   If you have a good reason to do this (disable Vampyre), please tell us (on forum or Discord) — we want to know about it. In the future, Vampyre may be just non-optional dependency of CGE, and we’ll integrate more and just use Vampyre as our image container in memory (right now we copy data between Vampyre and CGE TCastleImage, TGPUCompressedImage, instead of referencing it).

Documentation is the theme of recent news, as I work intensively on updating our manual 🙂

1. Added section about TCastleBehavior.

2. Improved X3D example to show building a mesh.

3. Update to user interface page is in progress, using an updated version of examples/component_gallery. It is not yet finished, but I feel it is already better.

4. Documentation about AAB (Android App Bundle) added, documentation about Android signing updated.

5. Logging docs updated.

6. Some outdated pages have been just removed, as they were outdated and described stuff of low importance (like TCastleOnScreenMenu, that is nowadays easier to do as just TCastleVerticalGroup with a number of buttons). Also the order of pages have been reworked, to put most important things at the top.

I implemented TCastleTransformReference to reference another TCastleTransform within the same viewport. This is an efficient way to use the same TCastleTransform multiple times, which is great for memory and speed. Consider using this when you need a lot of copies of something, e.g. lots of trees or grass patches.

All the TCastleTransformReference instances share the same state with the original, e.g. they will play the same animation. In practice, you will probably most often use this with static (not animated) models.

The detailed usage documentation is already part of the manual, at the bottom of “Tutorial: Designing a 3D world” page.

Note: from code, you can even just place the same TCastleTransform instance multiple times within the same viewport using code, even without TCastleTransformReference. This is documented too.

If you haven’t yet compiled any application for Android, now is the best time!

1. First of all, our documentation how to setup Android tools and build your first Android application is now much shorter and easier to follow. It properly documents now:

   • The easiest approach to installing Android SDK. I removed a lot of outdated steps that you don’t have to do.

   • It clearly advises fpcupdeluxe and explains how to use it.

   • It documents using CGE editor to switch platforms, build + install + run on Android.

2. Android building now works with latest Java 17. No need for downgrading to older Java, because older Gradle wrapper couldn’t handle it.

3. The default Android target platform is now 31. Previously we targeted platform 29. Due to Google Play requirements we had to upgrade to 30, and we decided to take it one step further to 31. (required by latest androidx.core).

With huge thanks to Rick Lentz, I now have Oculus Quest 2 at my disposal! Which means that we’re absolutely going to port Castle Game Engine, with all games and tools (like view3dscene) to it, as our first VR device.

Don’t ask me yet about the timeline 🙂 I’m after a quick 1 hour fun, and enabling “Developer Mode” and scanning Develop for the Quest Platform documentation just now. For us, the Native Development section is relevant, which means that the device can be like a “very special case of Android” from CGE point of view. Which is of course great for us, it means that all technology is just openly documented and we can utilize our integration with regular Android as a basis.

I know, buying VR device was supposed to be our goal on Patreon when we reach 500 USD / month. Well, Christmas came earlier 🙂 Please support the engine development through Patreon, this is what allows us to spend time on new platforms like this!

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!

Chapters:

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.

Writing engine documentation is so much easier now! In progress: I’m writing important new manual chapters about using viewport within the editor. It is really easier now with AsciiDoctor + macros I describe below, the improvements to our website infrastructure were absolutely worth it.

Following my plans, I have addressed 2 “pain points” of writing documentation: easily linking to API docs and embedding images. Now in AsciiDoctor you can use macros cgeref, cgeimg to easily add a reference / images. Sample of usage:

References to API docs: 

* cgeref:TCastleScene[]
* cgeref:ApplicationProperties[]

// You don't need to care in which unit they are defined.
// You don't need to care how PasDoc generates link to them
// (using anchors, like for procedures, or special pages, like for classes).
// Uses new PasDoc PHP output.

Some images:

cgeimg::block[aaa.png|Description of AAA]
cgeimg::float[dragon_0_wire.png|Dragon,gamma_nogamma_helmet.png|Gamma Correction]
cgeimg::float[
  dragon_0_wire.png|Dragon,
  gamma_nogamma_helmet.png|Gamma Correction
]

// The thumbnails will be auto-generated. 
// The syntax is short, and just exposes the 2 image layouts we need: 
// on the side, or within the main content flow.

I wrote extensive documentation of them in cge-www README.

Analogous PHP functions cgeref, cgeimg can be used in PHP.

Analogous WordPress shortcodes cgeref, cgeimg can be used for WordPress news posts.

Future:

• We’ll keep the current separation of WordPress vs AsciiDoctor for some time. This works nicely: Use WordPress for news, use AsciiDoctor for non-news. AsciiDoctor is better for version control and grepping. WordPress is better for auto-sending to other social platforms. Maybe a different resolution of this will come one day, for now the current situation actually addresses all needs (for news and non-news) best.

• The PHP way of writing docs is obsolete. With time, we will migrate all or almost-all of our documentation to AsciiDoctor (I already wrote some EmacsLisp helpers that I’m using for this). I suspect some exceptions (like main page) may remain custom-coded in PHP, but these will be exceptions.