Units Map

1. Introduction

Castle Game Engine includes a lot of units. They are divided into groups, which correspond to the subdirectories in the engine src subdirectory: transform, audio and so on. The groups are shortly described below.

2. Dependencies

One of the ways how we keep the engine maintainable is to limit the dependencies between unit groups. For example, the transformation and UI stuff depends on images, but the units in the images group cannot depend on units in the transform or ui groups. A simple dependency tree allows to easily debug some hard problems (when you want to strip the used units, to get to the "bottom of the problem").

The allowed dependencies are listed below. In short, the list of subdirectories goes from "lower level" to "higher level" in the sections below.

These dependencies are automatically checked (by tools/internal/check_units_dependencies, executed by Jenkins after every push).

Note
Temporarily, some units are allowed exception to break from this rule. Right now 3 units have such exception, i.e. they actually break dependencies outlined below. See AllowedExceptions list in check_units_dependencies. This is a TODO — we will fix those. It’s also a practical decision — while we want to watch over these dependencies, in practice breakage (in some cases) has no bad consequences.

3. Unit groups

3.1. castle_base package

3.1.1. base

Basic utilities and classes. Stuff for dealing with vectors, colors, strings, Unicode, logging, rectangles…​

Depends on: nothing else.

3.1.2. files

Files, URLs, XML utilities, downloading files from the network. See manual about network and downloading.

Depends on: everything above (that is, units in "base" group).

3.1.3. audio

Sound files loading, sound playback (including 3D sound), processing of sound files. See manual about sound.

Depends on: everything above (that is, units in "base" and "files" groups).

3.1.4. images

Image loading and saving: TCastleImage, TGPUCompressedImage (with ancestor TEncodedImage).

Depends on: everything above except audio.

3.1.5. base_rendering

OpenGL(ES) basic units. Headers, loading images/textures to OpenGL(ES), rendering basic 2D primitives (TDrawableImage, DrawPrimitive2D).

Depends on: everything above except audio.

3.1.6. fonts

Loading font data from files using FreeType, rendering text (TCastleFont), converting font data to be embeddable as Pascal units.

Depends on: everything above except audio.

3.1.7. ui

2D user interface of the engine: TCastleContainer, TCastleUserInterface, lots of TCastleUserInterface descendants like buttons, rectangles, labels…​ Also keyboard, mouse and other input handling.

Depends on: everything above.

3.1.8. services

Integration with environment (operating system). Opening a document, making a mobile payment, sending analytics data…​

Note
The unit CastleMessaging, important for Android services and iOS services, is inside the base group, not here. Reason: nearly everything else can use it, e.g. sound engine needs to use it.

Depends on: everything above.

3.1.9. transform

Basic transformation stuff, in particular TCastleTransform, TCastleCamera. Also quaternions, axis-aligned bounding box types.

Depends on: everything above.

3.1.10. castlescript

Parsing and executing expressions and programs in the CastleScript language.

Depends on: everything above.

3.1.11. scene

The core of our engine rendering and processing for typical games:

  • TCastleScene: loading many 2D and 3D formats, rendering, writing and processing (animating, collisions..).

  • TCastleViewport to display 2D and 3D scenes.

Depends on: everything above.

Subdirectories:

scene/x3d

2 big units that define all X3D base concepts: X3DFields, X3DNodes.

scene/load

X3DLoad and friends to load particular scene formats. Some formats have their own subdirectory, like scene/load/spine/.

3.2. castle_window package

3.2.1. window

TCastleWindow, window with an OpenGL context.

Depends on: castlescript.

Note
In the past it depended on more (even scene) but there should not be a need for this now. The container (TCastleContainer, inside TCastleWindow) allows to add TCastleUserInterface and TCastleView inside, and that’s enough, there’s no need for window to deal with viewports/scenes specifics directly.

3.3. castle_components package

3.3.1. lcl

TCastleControl, a Lazarus component to render with our engine.

Depends on: ui. (not castlescript for now, doesn’t need it.)

This is an alternative to TCastleWindow, so it has the same dependencies. Units between window and components group cannot use each other.

Note
In the past it depended on more (even scene) but there should not be a need for this now. The container (TCastleContainer, inside TCastleControl) allows to add TCastleUserInterface and TCastleView inside, and that’s enough, there’s no need for control to deal with viewports/scenes specifics directly.

To improve this documentation just edit this page and create a pull request to cge-www repository.