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.

Following my recent post, I am working intensively on CGE documentation updates.

PasDoc is a Pascal documentation generator, used by Castle Game Engine and many other projects. As it happens, I (Michalis) am also the developer of PasDoc now 🙂

To make it easier to develop a certain macro on CGE website, I have added a PHP output to PasDoc. This generates a map, in PHP language, that allows to map Pascal identifier name -> HTML page containing documentation for it. It allows our documentation (using a mix of AsciiDoctor, PHP, WordPress now) to be more aware of CGE API, and easily link/search to it. See the documentation of PHP output in PasDoc for examples how you can use this.

I hope you enjoyed the packed series of Castle Game Engine news last week.

It’s time for the first news in 2022: summary of 2021 and plans for 2022!

Before we start, I want to thank everyone who contributed to the engine in 2021. Together, we work on making a great open-source game engine. I have really big plans for what we can achieve in the future. Thank you for joining me in this!

Most important things we did in 2021

1. 7.0-alpha.1 release with loads of new features.

2. Sprite Sheet editor, to easily design and use sprite sheets (see news).

3. Many improvements to TUIState possibilities, docs, creating new state in editor.

4. TCastleBehavior, a way to enhance TCastleTransform behavior.

5. Designing fonts, sounds, other non-visual components in the editor.

6. Primitives like box, sphere, 3D text in editor for easily designing.

7. Many platformer demo updates, it is also on itch.io now.

8. While not yet part of CGE repo, we have 2 approaches for particle effects in CGE being developed.

9. Inspector available under F8 in any debug game.

10. Delphi port, merged to CGE master now.

11. Integration with Vampyre Imaging Library.

Plans for 2022

Definitely:

1. Editor improvements for 3D and 2D levels design:

   1. Better camera/navigation in the CGE editor. Like in most other 3D applications, the “camera that will be used at start of the game” should be a normal 3D entity in the world, separate from “camera that is used at design-time”. See TCastleCameraTransform in examples/creature_behaviors/code/ for start of it.

      Right now, design-time camera/navigation and runtime camera/navigation are the same, which makes it esp. cumbersome to switch navigation for design-time when you don’t want to change the mode for runtime.

   2. Ability to modify lights in CGE editor. New classes TCastlePointLight, TCastleSpotLight, TCastleDirectionalLight, TCastleEnvironmentLight.

      Right now, you have to set up lights in 3D authoring software (like Blender), and export to glTF. At runtime you can modify lights using X3D nodes for lights.

   3. Ability to modify materials in CGE editor of the TCastleScene. Materials present is scene (with names derived from underlying names in glTF, X3D etc.) should be slots that you can configure in the editor. This should also extend currente material config at primitives, like TCastleBox and TCastleSphere.

      Right now, you have to configure materials in 3D authoring software (like Blender). At runtime you can modify materials using X3D nodes for materials.

   4. Physics components (TRigidBody, TCollider and descendants) expressed as behaviors, and with auto-size by default. You should be able to design and test CGE physics in our editor.

   5. Utilities for typical 3D games (CreatureCreatures / CastleResources / CastleLevels / CastleItems / CastlePlayer) should be replaced with a better API and everything should be easy to make in editor. See planned features.

      New class TCastleMoveAttack and remake examples/fps_game/ demo to be designed 100% in editor.

2. Official Steam integration in CGE. We already used it for The Unholy Society, we want to either “just publish that approach” or propose a new, improved (without an intermediate “wrapper” library) approach.

3. Nodes optimization. Our current X3D nodes are unnecessarily heavy on memory. This matters in some cases, if you’d like to compose your game world from lots of scenes. This is already in progress, provoked by issue #285.

4. Documentation and promotion:

   1. Upgrade of the main page to emphasize our features.

   2. Upgrades of the documentation to describe the editor, as I outlined in previous post.

   3. We need to gain more users of the engine. Esp. now that we have Delphi compatibility, which opens us for more devs.

5. Engine 7.0-alpha2 release ASAP (in January 2022, after some documentation updates).

6. Engine 7.0 release in 2022!

7. WebGL port, using recently announced FPC WebAssembly target!

   Yeah — we already planned WebGL port using pure pas2js. Using FPC+WebAssembly means that it is easier to do and result will be more efficient.

Maybe:

1. Physics abstraction layer, with alternative physics engine being Bullet.

2. Rendering abstraction layer, with alternative renderer being Vulkan.

3. Explore USD – Universal Scene Description support, as a first-class citizen, alongside glTF and X3D.

4. Terrain designer, see planned features.

Documentation upgrades done lately

Lots of documentation (in particular from wiki) was reworked, simplified, updated, consolidated with other pages… See in particular:

• Build Tool
• CastleEngineManifest.xml – Syntax and Examples
• Android Services (each particular service now has a dedicated documentation page)
• iOS Services (each particular service now has a dedicated documentation page)
• glTF
• Sprite sheets
• Coding conventions
• Lots of new pages are now linked from documentation sidebar. Browse them! 🙂

We converted 100% of our GitHub wiki contents to AsciiDoctor. This was done using kramdown-asciidoc and lots of manual tweaking.

Resulting AsciiDoctor sources are here. Editing them is trivial, and the HTMLs are auto-regenerated when updating the website. Note also the text To improve this documentation just edit the source of this page in AsciiDoctor (simple wiki-like syntax)…. at the bottom of new pages, with ready links to edit each page!

We have pretty URLs for pages generated by AsciiDoctor. So now we have https://castle-engine.io/build_tool instead of previous https://github.com/castle-engine/castle-engine/wiki/Build-Tool.

We also have nicer “404 not found” page now, try it: https://castle-engine.io/not_existing.

Why?

I was thinking lately of updates to our documentation. They come down to 2 big things:

1. Main page rework, to emphasize all our features using screenshots.

   For this, it is obvious I should just follow one of the numerous templates. We already use WordPress (for news) and own theme using Bootstrap. So we can easily adapt one of the numerous WordPress / bare Bootstrap templates.

2. Lots of manual updates, to document the fact that you can (and should, in simple cases) do many of the basic things using the editor. E.g. current manual describes usage of TCastleScene from code (and disregarding typical cross-platform app organization, that we advise). It should instead describe using TCastleScene from editor, and from code too, and placing most stuff in TUIState instances.

   I can pinpoint some pain-points of editing current docs in our PHP website:

   1. Writing API references is tiresome (need to spell out part of the generated URL).

   2. Adding images is tiresome (it breaks the workflow, to add new image, which is troublesome as lots of manual pages should get more screenshots).

   3. Formatting is a bit tiresome, and in effect we had docs spread between manual PHP/HTML and GitHub wiki.

Thoughts: Various approaches to documentation

I used a number of approaches for online documentation throughout my life, and within CGE.

• DocBook (e.g. for compositing shaders (to both HTML and PDF), my Ph.D thesis),

• LaTeX (e.g. for shadow maps paper).

• AsciiDoctor: I used this for modern Pascal introduction, sources on GitHub.

  This is very comfortable for editing, markup language is wiki-like (but can be processed reliably by more tools, as AsciiDoctor is more standardized than Markdown).

  The output is customizable, so it can be made to fit within a website.

• Jekyll (I used it for PasDoc website):

  + excellent version control integration, you commit markup (e.g. using Markdown or AsciiDoctor) to version control

  + secure: you just generate HTML, and put it on your website. No need for server-side or client-side scripting, when you can just put HTMLs on your website, when all you need is a static website.

• News using WordPress: WordPress is good, esp. I like

  + customizable shortcodes (e.g. to solve the “easy way to add API docs links”)

  + easy way to edit news

  + easy way to upload images

  My main concern of doing 100% content in WordPress is that you don’t have version-control support. While WordPress has versioning, it is nowhere as comfortable as “just a bunch of text files in a GIT repo”.

  + we want to use existing templates for WordPress sites. So using WordPress is beneficial to be able to use existing themes.

• GitHub wiki:

  + easy to use mark-up language, as above

  – lack of ways to customize it, looks like alien when mixed with our website

  – cannot add images, you have to upload them to normal website manually anyway. So adding images is least comfortable in this case, which makes it a “no-go” for our documentation that should have lots of screenshots.

  – lack of http redirects

• Our website using hand-crafted PHP with theme based on Bootstrap, which is our current main way to write website:

  + 100% flexible

  + PHP performed some part of “customizable shortcodes” that we need

  + looks native, we do what we want, using common theme, manual headers, automatic ToCs etc.

  – still some work to add new images, this is tiresome when writing documentation with lots of screenshots. You put them in htdocs/images/original_size, run make, add PHP/HTML code to include them.

We need to make improvements:

1. easy uploading images to current cge-www images/ , autogenerate their thumbnails

   This can be extension of current PHP code.

   A tag that adds images, and allows to upload image also in special website mode.

2. easy shortcode to add API docs.

   This can be extension of current PHP code (apidoc can be easier, to take auto-generated PHP table of Pascal identifiers). We already have PHP function used like <?php api_link('TCastleScene', 'CastleScene.TCastleScene.html'); ?>, we need to make it less tiresome, so that I can write just <?php api_link('TCastleScene'); ?> and it will find in what unit it is.

   Then it can be a WordPress shortcode too.

3. One markup, comfortable. Also replace GitHub wiki with it.

   My choice: AsciiDoctor, this proved right for modern Pascal introduction and later for
   PasDoc website. The fact that Khronos decided to use it for glTF specification is an outside confirmation that it’s good.

   Markdown can be converted to it using https://github.com/asciidoctor/kramdown-asciidoc + some manual tweaking for one-time conversion.

I hope you find these thoughts useful 🙂 These plans have been followed by actions — see section Documentation upgrades done lately above.

Please support the engine development on our Patreon. It funds development of the engine, including the efforts to document it perfectly.

Thanks to the related Lazarus issue being fixed by Juha Manninen, our editor can now open Pascal files in the proper Lazarus project reliably if you use Lazarus >= 2.2.

We also query Lazarus version, to activate new behavior only for new Lazarus. You should see your Lazarus version in the editor preferences window.

I have just released a new version of glplotter, a small utility implemented using Castle Game Engine to draw graphs. Graphs can be defined using an intuitive mathematical expression syntax (thanks to Castle Script). Multiple graphs are visible at the same time, and you can inspect the function graphs by moving, zooming, toggling various grids and scales.

Everything is documented on glplotter webpage. The source code is on the project’s GitHub page. The released binaries are on GitHub releases.

Please support the engine development on our Patreon. It funds development of the engine, along with all the extra tools.