Documentation enhancements: using children components, API and code conventions about memory management, nils, BeforeDestruction and more

News
1
Raspberry Pi Pico by abdoubouam from https://sketchfab.com/3d-models/raspberry-pi-pico-79aba8c863a14b4682e34e241f2159d2

We have a number of enhancements to our 2 large documentation pages (targeting mostly advanced engine users / developers):

  1. Custom Components documentation was extended with description how do we advise to create children components in your custom components. This is useful when you want to create a new component, register it in CGE editor, and you want to use existing components as children.

    1. You can have internal children (using SetTransient).

    2. You can create regular components in OnCreate method that the user can later completely change and even remove (free).

    3. You can have subcomponents (where user can configure properties, but shouldn’t free / assign a different instance).

    All cases are documented with example code.

  2. We have a big Coding Conventions page that documents a lot of low-level and high-level guidelines about how the engine is developed. It starts with some mundane stuff (like indentation — 2 spaces, never tabs!) but later discussed more interesting topics that I recommend to read:

    1. Our guidelines for BeforeDestruction usage. Big thanks for Andrzej Kilijański for talking it over with me — it’s a very powerful mechanism when combined with clear guidelines when to use it.

    2. You can (and should) free the things you allocated; you should never free other things, unless explicitly allowed.

    3. What can be nil.

    4. Declarative API (classes with independent properties) is simple to use.

    5. Optimize smartly: profile, optimize where it matters (and not where it doesn’t), think about smarter algorithms and moving CPU work to GPU to get big benefits.

    6. Fix warnings (let the compiler help you write reliable code). (Shining example: recent critical TCastleThirdPersonNavigation fix for seemingly-random bug.)

    7. Be consistent in API design.

    8. Backward compatibility is important; having a consistent (easy to learn) API and useful features is even more important.

This post’s image follows our tradition if there’s no clear image to illustrate this, just search for any pretty 3D model. It turns out that if you search for “documentation” on Sketchfab, one of the things that comes up are 3D models of Raspberry Pi, which we love and support in CGE (both as a platform where you can work, and as a platform to which you can compile your games). So here’s a screenshot of CGE editor rendering a 3D model of Raspberry Pi Pico by abdou bouam.

1 Like