Announcing a variety of documentation and website improvements:

1. For starters, we prepared slides highlighting Castle Game Engine features and plans. These are a nice summary of what we do and why. Just 11 slides, deliberately a short presentation. I very recommend to read and share it with everyone who may be interested in our engine!

   It has been prepared for Nicholas Polys to present our engine at SIGGRAPH 2024 highlights.

2. We have a big new section about “Baking Lighting” in our Blender documentation. This is a very powerful Blender feature, and it naturally works great in combination with our engine. We hope that this documentation helps you use it (there are a few “tricky” things to click during the process). It is accompanied with screenshots and sample model using it, in demo-models/blender/baking_lighting.

3. Inspired by a topic on our Discord, I added a section Variant records and related concepts to our modern Object Pascal introduction.

   It describes 3 Pascal features, all with examples:

   1. Variant records (example)

   2. Variant type (example)

   3. array of const and TVarRec (example)

4. We added a search box to our documentation, relying on DuckDuckGo (a privacy-friendly search engine that I use, instead of Google, for many years now, and don’t look back 🙂 ). It’s a simple search box that you can find at the bottom of the left sidebar on any page within the “Documentation” section. It searches everything in our domain that was indexed — docs, API reference, and even forum.

5. We updated and simplified our page about X3D. We tried to make it more streamlined and focus on important things (it’s an open standard and we use X3D nodes for everything). We hope this is simpler to digest than the previous version, which was complicated, at some points needlessly (e.g. most people by now probably don’t care about VRML).

6. We improved our roadmap, clearly distinguishing what we plan to do for 7.0.

7. A shout out to Reddit users: did you know we have a place to talk about Castle Game Engine on Reddit? Join there and feel welcome to talk about the engine. Eugene Loza reposts our news there, you can jump-in and comment on any news, or just start a new topic about anything you’d like.

We’re proud to officially release today Castle Model Viewer for Android!

Get it now from Google Play.

It’s a free 3D and 2D model viewer that supports all Castle Game Engine model formats: glTF, X3D, VRML, Spine JSON, sprite sheets, MD3, Wavefront OBJ, 3DS, STL, Collada, and more. It also allows to open a ZIP file that contains a single model and associated media (like textures, sounds etc.).

The viewer includes a few demo models built-in, but naturally you can also open your own model files. The important thing to remember is that models must be self-contained — we explain exactly what this means in the documentation, but the short version is: you will probably want to pack model with textures into ZIP.

Features:

• You can change navigation type (walk, fly, examine, 2D),

• jump between viewpoints,

• play chosen animations,

• save a screenshot,

• display scene statistics (triangle, vertex count) and more.

• Overall, we included the features from our desktop viewer that have been most useful, and adapted them to the mobile UI.

Have fun! If you find it useful, please support us on Patreon or a number of other ways.

The viewer is free, open-source, and has no ads or tracking naturally. Enjoy open 3D standards!

If you have any feedback, you know where to find me 🙂 Report bugs as GitHub issues. Oh, and if you like it — we’ll appreciate a 5.0 rating on Google Play 🙂

Big thanks for developing initial version of this application (originally known as view3dscene-mobile) to Jan Adamec, long-time contributor to our engine, also author of e.g. Room Arranger. It took us a lot of time before making a public release but here it finally is! Thank you!

1. We have released our Platformer game on Google Play! It’s a full-featured 2D platformer game, with sources available inside the engine, in examples/platformer subdirectory.

   The Platformer release on itch.io has also been upgraded. The new platformer version features a helpful dialog showing how to control the game on mobile, and pause view improvements (dimmed background, consistent Escape key on desktop, pause button on mobile).

2. New menu item in editor to debug input behavior: “Run -> Run Parameters -> Pretend Touch Device”. Accompanied by a command-line parameter --pretend-touch-device.

3. Extended our touch input documentation: more about TCastleTouchNavigation, mentioned compilation symbols, example using ApplicationProperties.TouchDevice.

4. Fixed the check when setting “Android SDK Location” from the editor, because the latest Android SDK may not have tools subdirectory.

5. Fixed stopping (from editor) an application running on Android from Unix. Previously, it always left adb logcat process in the background, and made a warning about incorrect child id. Now it properly kills adb logcat.

6. We bumped the Android target API to 34 (Android 14) to match the upcoming Google Play requirements.

We work intensively on the engine! Here’s a list of smaller engine improvements / fixes done recently. (For bigger improvements, see all the recent news — we have a lot of new stuff.)

1. New simple API in our CastleUnicode unit: TCastleStringIterator, UnicodeCharToString, UnicodeCharToReadableString, StringWithHtmlEntities. All with auto-tests. All following our general rule that when used with FPC, we follow default Lazarus conventions: String is AnsiString and it holds UTF-8; when used with Delphi, we follow default Delphi conventions: String is UnicodeString and it holds UTF-16.

2. We’ve made important fix to our VS Code extension last month: we now pass engine path properly to the LSP when the engine path has been configured as VS Code extension setting.

   Previously, our VS Code extension only worked if you had set CASTLE_ENGINE_PATH environment variable… which was not our intention, this was just a bug. To be clear, we work a lot to not require regular users from ever setting CASTLE_ENGINE_PATH environment variable (or any other environment variable, for that matter, like PATH). Because setting environment variables, in a way that is applied to all applications run in any way (also e.g. GUI applications not run from a shell), and on all operating systems (Windows, Linux/FreeBSD, macOS)… is not that trivial, as experience shows.

3. I wrote a small page documenting how overloading Pascal works, with or without the oveload keyword.

4. Optimized DPROJ size when your project has huge number of data files (we still need to list them all, for Delphi non-Windows targets, see Data files deployment (applies to all non-Windows platforms with Delphi), but the DPROJ shouldn’t be that big anymore).

5. New example examples/user_interface/screen_resolution_change showing how to use Application.TryVideoChange to change the monitor physical resolution. Along with a README that warns when it may not be the best idea 🙂 Using UI scaling is our first recommendation to make a game that adjusts to arbitrary user screen size.

6. You can now drag and drop Tiled maps on the viewport.

7. Docker image upgrades:

   • Updated Compressonator version in the image.

   • Updated FPC and Lazarus “latest” versions, see here for latest GIT hashes from FPC / Lazarus GitLab repos.

   • Updated GitHub CLI version.

   • Added git-lfs to checkout large repos (in case of GitHub Actions, they are checked out inside Docker image, unlike in case of Jenkins).

   • Fixed updating all Docker images hosted on GitHub in addition to Docker Hub

   • Repo is now castle-engine/castle-engine-docker (less sexy but more obvious name for previous “castle-engine/castle-engine-cloud-builds-tools”) 🙂

8. We now warn if it seems you mix 2 engine versions.

   The mix means that it seems the tools you call (in particular build tool, also called by editor) are accompanied by one engine version, but you use CASTLE_ENGINE_PATH environment variable to force a different engine location. This is a strong indicator that you have a mistake in your setup (maybe you forgot you have a CASTLE_ENGINE_PATH pointing to some old engine version) and can lead to various weird problems (since given build tool expects a given engine layout). Now you will get a clear message about it, like

   “$CASTLE_ENGINE_PATH environment variable points to a different directory than the one detected from the executable path: “…” vs “…”. This may be a mistake, possibly you have two (different) engine versions installed. Please check your environment, likely remove one of the engine versions or undefine CASTLE_ENGINE_PATH to not point to the engine that shall be unused.

   To be clear. you can have multiple engine versions on your machine. Just be sure to always use the tools (like build tool) from the same engine version from which you use sources (and build tool data).

   To avoid confusion, if you are unsure, we generally advise to not use CASTLE_ENGINE_PATH (as a central variable pointing to “current” engine) and do not put CGE tools on PATH. The less “central” settings you have -> the less things you have to maintain 🙂 If you don’t have any environment variable like CASTLE_ENGINE_PATH, but just run “bin/castle-editor”, it will correctly pick up the tools (including build tool) from the same engine directory. There are exceptions when CASTLE_ENGINE_PATH is useful, but you need to know what you’re doing :), in particular you need to remember that it’s another place where you indicated “where is the engine” and you will have to update it, if you decide to juggle engine versions.

9. Nothing done: We have been testing switching FPC optimization in release builds from -O2 or -O3. Sadly, it creates bugs in Aarch64, so we reverted back to -O2.

I don’t have a perfect image to illustrate this post. Attaching a screenshot showing how to display a cat with a jetpack instead :), because we can.

Do you like what we do? We appreciate your support on Patreon!

If a project is compiled in debug mode you can enter an Inspector at any time by pressing F8 or (useful on mobile) holding 3 fingers anywhere on the screen for at least 1 second.

The Inspector, first introduced in this video, is a tool to debug your game as it is running. It features an editor-like interface, to inspect your hierarchy and components, view logs, profile (measure speed) and other important tools. Recent news item alreday talked about “Monitor and Auto-Reload Data” checkbox.

We continue to extend this with more features, to make debugging and experimenting with your game as it is running more powerful.

1. The biggest feature here is that you can manipulate boolean properties as checkboxes. For example, just click on the TCastleUserInterface.Exists or TCastleTransform.Exists to toggle whether something exists (is visible and collidable). Toggle TCastleImageTransform.SmoothScaling to tell if an image is pixel-art or not. And so on.

   TODO: We want to extend it to allow editing all properties at runtime, not just booleans. This improvement should come very soon, editing properties as strings is a natural extension of this idea. And naturally this is pushing us more and more into idea “implement editor using CGE UI”, something that we already committed to doing, but it’s going to take some time.

2. Pretty hierarchy rendering (no more “-” suffixes).

3. Display user interface and viewport stats (draw calls).

4. Checkbox to toggle UI batching. Select “More” and then “User Interface Batching”.

   Note: you can also toggle viewport batching, just select the viewport and toggle TCastleViewport.DynamicBatching property as a checkbox.

A natural warning: This is a debug feature that may break some assumptions in your code. If your Pascal code assumed that it controls the TCastleTransform.Exists value (which is a perfectly valid assumption, it is true when your game is actually used by normal people!) then you can break this assumption. That’s also why the release game builds naturally don’t enable the inspector. You can control whether the inspector is possible adjusting the TCastleContainer.InputInspector configuration — e.g. you can make inspector always disabled, or always enabled, or enabled using some other key combination.

To be enabled by default only in debug mode, inspector relies on specific project configuration set up in new project and updated by “Code -> Regenerate Project”. More specifically, the call ApplicationProperties.InitializeDebug; in CastleAutoGenerated.pas unit makes the inspector available (using F8 or 3 fingers). See also our recent post about “Code -> Regenerate Project”.

We added to Castle Game Engine capability to read 16-bit and higher precision image formats. This is useful for precise terrains (where you want to store heightmaps with more precision than 8-bit) or any other data that you may want to process (in shaders or using Pascal code) where 0..255 range (8-bit integer, i.e. byte) is not enough.

Overall, this is a collection of inter-connected features and developments. We hope you enjoy our long news announcements :), here goes:

1. First of all, grab the demo test-high-precision-terrains: Test loading terrains from 16-bit and higher precision image formats. It’s in a separate repository (not in CGE main repo) because it necessarily has quite large data files.

   Just explore it, in editor and also run it, to see what this all means.

2. We have implemented a full set of 4 float-based image formats:

   1. TGrayscaleFloatImage,
   2. TGrayscaleAlphaFloatImage,
   3. TRGBFloatImage,
   4. TRGBAlphaFloatImage.

   All these float-based image formats are now uploaded to GPU as float textures, thus can be used to process this data on GPU in shaders. That is, we don’t “lose” the extra precision anywhere on the way from disk to the GPU.

   For example, new Castle Image Viewer loads and displays the 16-bit PNGs, or float-based KTX, or 16/32-bit TIFFs, as float images. You can confirm it by loading such image and observing that Castle Image Viewer status bar shows it has a TXxxFloatImage class.

3. 16-bit PNG images can be loaded to 4 float-based image formats mentioned above. (Previously, they have been loaded to 8-bit image formats, losing precision.)

   There’s nothing you need to do to enable it. The 16-bit PNGs are just loaded to new image formats now, and everything should just work better.

   This happens both when PNG images are read using LibPng (our default PNG handling, giving us great PNG loading performance) and Vampyre Imaging Library (as a fallback).

   In both cases, we now read all images from PNG test suite perfectly, without any precision lost. We have included some images from that test suite into CGE auto-tests to ensure it stays this way.

4. Float-based KTX images can be loaded to 4 float-based image formats mentioned above. This is great if you really need max precision. KTX contains float values, we read float values, there’s no conversion at all — everything is simple, fast, and using floats.

   Note: throughout this announcement, “float” means the 32-bit floating point type called float in C and Single in Pascal. All image libraries, including Vampyre and CGE, call it “float”. Do not confuse this with Pascal Float type defined in the Math unit, which is the most precise floating-point format and not that useful for cross-platform applications since it means something different on different platforms.

   I found test KTX float images in KTX software, more precisely inside the astc-encoder tests (look in HDR-RGB and HDR-RGBA subdirs for suffix 32.ktx).

   These test images are also included now in CGE auto-tests (tests/data/ktx/floats) to ensure they are loaded correctly forever.

5. Likewise, 16/32-bit TIFF images can be loaded to float-based image formats mentioned above.

   Note that TIFF reading capability is not enabled by default in CGE. You have to enable TIFF support in your application and distribute the TIFF library (libtiff) with your application. We have documented it better now:

   • Read details about TIFF and JPEG 2000 support – why it is disabled by default, and how to enable it. This document also describes how to build and use libtiff.so.5 necessary to make it work on Linux, and what happens on other platforms.

   • Castle Image Viewer branch extra-image-formats is a working example doing it. You can compile this to get castle-image-viewer with TIFF and JPEG 2000 support. It includes the libtiff.so.5 precompiled, ready to use.

   Test TIFFs are in the test-high-precision-terrains demo mentioned above, see data/test_tiff.

6. TCastleTerrainImage uses TGrayscaleFloatImage to read terrain data from images. This means that it always operates on float precision, and you will enjoy extra precision if you image contains it — that is, if you use 16-bit PNG, or float-based KTX, or 16/32-bit TIFF.

7. Our Castle Image Viewer (test the snapshot version) also got some improvements along the way:

   • Refactored old long code into a few nice units.

   • Previous “Image information” modal dialog is removed…

   • … Because we have a new status text. Toggable with F1. Looking similar to Castle Model Viewer status text — deliberately. Displays lots of useful image information.

   • The “Images” menu is properly updated when opening the image with directory using “o”.

   • The files loaded from the directory are sorted.

   Overall, you can now browse a directory with images and quickly see their format, sizes etc. This is available on both master and extra-image-formats branches of castle-image-viewer.

   For quickly checking a lot of file formats/sizes, remember you can also use CGE existing utility image_identify. Great to check from command-line a number of images. Combine with Unix find to scan a whole directory, recursively, and output image information. Inspired by ImageMagick’s identify.

8. Note: saving float-based images is a TODO. It is documented in the roadmap. As always, ping me if you need it.

Credits

Big thanks go to Erik Johnson for supporting Castle Game Engine development, both on Patreon and by actually using the engine to develop new projects, and providing a ton of useful feedback on our forum! See the forum thread that initiated this.

The sample data has been provided by:

• Landscape Height Maps – great detailed terrains, including 16-bit PNG images.

• Topographical Earth Tutorials for the big 16-bit TIFF image.

Engine features described in this post done by Michalis — thanks to your support.

When working in the editor, we now automatically reload images and Tiled maps when they change on disk. This means that you can edit image e.g. in GIMP, save it, and just Alt + Tab back to the editor to see the new image displayed as part of UI or in the viewport. Similarly, you can edit and save the map in Tiled and just switch back to the editor to see the new map.

This is in addition to our earlier feature of auto-reloading the scenes when the change, which allows to e.g. edit in Blender, export to glTF and then immediately see the update in CGE editor.

To be precise, components that now support automatic reloading are:

• Images in TCastleImageControl (see using images)
• Images in TCastleImageTransform (see using images)
• Tiled maps in TCastleTiledMap (see Tiled maps)
• Scenes TCastleScene (see viewport and scenes)

To take it a step further, you can enable this automatic activation also at run-time (when the game actually runs)! This allows to develop and test your game “live”, right as it runs. E.g. tweak a scene with 3D enemy, right when you actually see the given scene in the game. Or tweak an image right when you actually see it appear in the UI.

To enable this, enter the inspector (press F8 on desktop, by default) and select the checkbox “Monitor and Auto-Reload Data”. If you don’t see this checkbox, make sure you have regenerated your project files using the latest engine version.

Warning: Reloading the content at run-time cannot be a 100% safe operation in all the cases. In general, your project code may make assumptions that are true in “normal” project usage, but will be broken by reloading the image or scene. For example:

• Reloading image components means that image size may change in the middle of work. If you have been using the image size in some calculations, that calculation has to be redone now.

• Reloading TCastleScene means that all X3D nodes are freed, and then loaded back from file. If you have done some post-processing of a loaded scene, this will be lost. If you have saved some references to nodes (TX3DNode instances in MyScene.RootNode), they will be invalid after reloading.

  You could make these scenarios work, e.g. observe for node release using notification mechanism like TX3DNode.AddDestructionNotification or AnyNodeDestructionNotifications to set freed references to nil. Then reinitialize them on-demand. But it is completely understandable that you may also just ignore this issue — auto-reloading should not happen when regular users play a release version of your project. And the extra code to account for hot-reload could be an additional complication. It is your decision whether/when it is worth it.

• For the above reasons, we have also disabled for now “auto reload” for reusable designs (in TCastleDesign and TCastleTransformDesign, see reusable designs). Auto-reloading them could cause too many problems, since in most cases you keep references to some components inside loaded designs in your code — these references would become invalid.

  Although it is almost implemented.. but commented out. If you want to experiment, go ahead and test uncommenting it in castletransform_design.inc (for TCastleTransformDesign) and/or castlecontrols_design.inc (for TCastleDesign). I welcome feedback — if you feel that this feature is more useful than it is dangerous, we can make it active. Or introduce a 2nd checkbox like “Monitor and Auto-Reload ALL Data (dangerous!)”

This feature was inspired by Tomorrow Corporation Tech Demo. It’s quite amazing demo cranking such “hot reload” features “up to eleven” 🙂 Very advised to watch and be inspired!

Note: There are some known missing pieces related to reloading. Nothing is ever perfect 🙂 Comments and encouragements to extend this are welcome as usual. And this feels like a good place to remind that we cherish your support on Patreon – please support us if you can. Thank you!

The summary of this post is: Download latest engine and use “Code -> Regenerate Project” menu item in the editor. It will regenerate the files inside your project (DPR, LPI, DPROJ, and CastleAutoGenerated.pas unit).

We’ve made a few improvements to them, and all together it means we strongly advise you to regenerate your project. The improvements are outlined below, though their real “big outcome” is to unlock 2 new features I will announce in further news posts 🙂

Notes:

• As always, using the “Code -> Regenerate Project” is not strictly required by us.

  Just recommended, esp. if you develop a regular game following our “New Project” templates, and most examples, as seen in cross-platform manual. In such case, we advise you let us auto-generate your project files (as above: DPR, LPI, DPROJ, and CastleAutoGenerated.pas unit) and you only focus on putting code in units (like gameinitialize.pas, views, and of course as many additional units as you need).

  But if you develop something non-standard (like a Lazarus LCL or Delphi VCL / FMX application using TCastleControl) then you may prefer to manage the project yourself, manually. That’s cool too, engine will work perfectly, you will just have to activate some features explicitly, like starting logging (by InitializeLog) or debug features (by ApplicationProperties.InitializeDebug).

• Note that you can also do this from command-line: run castle-engine generate-program.

• As always for development, we recommend you have a backup, actually use a version control (like GIT, backed by a server like GitHub or GitLab) and check the differences caused by the regeneration. If you’re not using version control yet, you really should start :), there are lots of self-hosted and “cloud”-hosted options, also free, even for private (not public) projects.

After this long introduction, the things we improved:

1. Newly generated Lazarus (LPI) projects include Debug / Release build modes, that set common optimization/debug flags and define DEBUG / RELEASE symbols.

   This is consistent with what our build tool has been doing since ~always and how we configure Delphi projects.

2. The CastleAutoGenerated unit now calls ApplicationProperties.InitializeDebug or ApplicationProperties.InitializeRelease depending on the DEBUG define when compiling the project.

   This means we can do some stuff (like enabling inspector on F8 key, or file monitor — see future news!) regardless of whether the engine units were compiled with the DEBUG symbol or not.

   The idea is that the DEBUG symbol definition when compiling your project should matter, and the DEBUG symbol definition when compiling the engine should be something independent.

   Why? This allows to have pre-compiled engine, and the same engine (so, release) available for both debug and release projects. Right now compilation from our build tool actually compiles the engine and your project in the same mode (both are debug or both are release), and our advised Delphi compilation does the same. But it’s not going to be like this always. Compilation from Lazarus IDE using packages is already different: engine Lazarus packages are compiled with options independent from your project. Future Delphi integration may also mean you use engine units compiled once, from all projects.

   So we are getting ready for this, by “cleaning up” our debug/release relations between project and engine.

3. We fixed mixed-up Debug and Release settings in auto-generated Delphi (DPROJ) files.

   By a mistake, since a few months, the DPROJ files we have auto-generated had DEBUG and RELEASE options mixed up.

   That is, when you selected “Debug” from Delphi, we actually made a release build (with optimizations and with RELEASE compilation symbol). Conversely, when you selected “Release”, we actually made a debug build (without optimizations and with DEBUG compilation symbol defined). I know, silly bug, we just caught it. Sorry — but at least you can fix it with literally one click, just regenerate project.

   This is connected to the inspector (invoked by F8): It means that our debug build didn’t react to F8, while release builds did… Fixed now. Inspector (F8) is active in debug builds now.

As usual for a long post without clear thing to screenshot, I just show something pretty 🙂 The screnshot comes from Cyberpunk City (old project) by carlcapu9 licensed under CC-BY-4.0.

Today we have a treat for our Spanish users: our latest tutorial Bad way to play chess: 3D physics fun using Castle Game Engine is now available in Spanish!

Read it here:

1. Part 1 (installation, using editor, testing physics…).

2. Part 2 (coding).

Big thanks for this go to Jorge Turiel (aka BlueIcaro) and his blog where he frequently writes about Pascal and our engine. I’m sure you will enjoy this if you read Spanish, so be sure to check out the tutorial — highly recommended reading, this is our latest tutorial that is right now the best introduction to using the engine, showcasing all important engine features.

If you have any questions in Spanish or just wanted to say thank you to Jorge, please use the “Comments” section at the bottom of every linked article! And share the links with your fellow Spanish Pascal and Castle Game Engine users 🙂

In related news: I have rearranged our main page linking to this tutorial, to clearly link to all article versions, including the new Spanish. If you’d like to translate the tutorial to your language, we welcome it! Every approach is good. For example, you can host the translation on your own blog, if you so desire, just like Jorge does, and organize your local community. Or you can submit PR to our bad-chess repo, adding localized article versions inside the article/ subdirectory, like castle_game_engine_bad_chess_1_polish.adoc. I (Michalis) will then take care to review and link it everywhere.

Thank you everyone for together spreading the knowledge about our engine!

We have updated our Modern Object Pascal Introduction for Programmers. Enjoy!

The most important addition is the section about “Anonymous functions”. It’s mostly just a simple example (tested to compile with both FPC and Delphi) along with links to good Delphi and FPC documentation. The examples are also in the repository:

• anon_functions_list_map_foreach.dpr

• anonymous_functions.dpr

• anon_functions_assignment_test.dpr

The above examples probably do not really do “justice” to demonstrate anonymous functions capabilities. The big thing is that, as you can write the body of anonymous function inside a larger context, you can access the variables from that context. This means that there’s less need to invent “how to pass additional data to a callback”, which is a common need when using normal callbacks (to global routines or methods) that requires adding new fields or even classes that are useful only temporarily. Various details of this mechanism are documented in Delphi documentation (and the FPC implementation is compatible, from what I know).

While we cannot use the anonymous functions in CGE code (as we want to stay compatible with FPC >= 3.2.0, while anonymous functions are only in unstable FPC 3.3.1 for now). But there’s no reason why you couldn’t use them in your own projects, if you use Delphi or FPC 3.3.1. To install FPC 3.3.1 we recommend FpcUpDeluxe. In the CGE editor preferences, you can point to the FPC version you’d like to use, choosing any installation done by FpcUpDeluxe.

Another update is fix to Generics.Collections example showcasing sorting using custom comparer. Recent FPC versions change the required parameter type from constref to const (for Delphi compatibility as well as better code generation).

We have also updated the scripts of modern-pascal-introduction to ease updating everything when the content changes, and defined GitHub Actions to check that all code samples build correctly.