Upgrading to Castle Game Engine 7.0

TUIControl.RenderStyle is removed. It was a convoluted way to specify rendering order. Now, only the position of the control among the children (when you InsertFront, InsertBack etc.) determines the rendering order.

The default TCastleLabel color is now Black, not White. This compatibility break seemed unavoidable, unfortunately our UI controls were inconsistent — most assumed a modern "black colors over white background scheme" (TCastleEdit, TCastleRectangleControl, TCastleCheckbox…​), but TCastleLabel was by default white. So it e.g. was invisible over default TCastleRectangleControl.

The default TCastleSceneManager.BackgroundColor is now very dark gray Vector4(0.1, 0.1, 0.1, 1), instead of pure black Vector4(0, 0, 0, 1). This makes a better default, as pure black things (3D / 2D models, or user interface, like labels) are still visible over this background (as well as pure white things).

The user interface coordinates (all positions, sizes, as well as font sizes) are float-based now. See this post for details. In some cases, you may need to adjust your code. For example if you do SomeIntValue := MyOtherControl.Width div 2;, now you will have to change it to SomeFloatValue := MyOtherControl.Width / 2;.

The interpretation of FullSize=true is now consistent across all TCastleUserInterface ancestors. It always overrides the control to fill the parent.

TCastleImageControl.ProportionalScaling values psFit and psEnclose work a bit differently.

Anchors are always on now. The ability to turn them on / off in previous CGE versions was more confusing than helpful, and it was also useless.

Some components are no longer registered on the component palette. To bring them back (e.g. to open LFM files that refer to these components), you can define {$define CASTLE_REGISTER_ALL_COMPONENTS_IN_LAZARUS} to the src/castleconf.inc file. See this commit log for reasons.

TCastleFont.Scale was removed (as it was a trap, due to how it was implemented and specified, it was only working on some TCastleFont descendants). Use only TCastleFont.Size. For TTextureFont (which is the most commonly used font descendant) the Scale property is still present, so usually writing Font.Scale := 0.5 continues to work, if Font is of class TTextureFont.

By default, fonts show a fallback glyph (like "?") if you try to render a missing character in the font. This is usually a good idea — it allows the user to see that something is there (so e.g. "backspace" makes sense, otherwise you would "backspace" invisible characters sometimes), the developer knows that something is missing (the log will also contain warnings about missing characters). However, if you want to restore previous behavior (that silently ignores missing glyphs) set TTextureFont.FontData.UseFallbackGlyph := false.

TGLImage.ClipLine and TCastleImageControl.ClipLine are expressed in local (texture) image coordinates, in which image (X, Y) span from (0, 0) (bottom-left) to (1, 1) (top-right). Previously, they worked in the final screen coordinates. The new definition is much more useful, it allows to express common use-cases with a constant equation, e.g. reject left half of the image by ClipLine = (1, 0, 0.5), regardless of the image size and position on the screen. It also plays nicely with UI scaling — the previous definition was working in final device screen coordinates, and we avoid exposing them in UI API.

TCastleButton.Image and 4x TCastleButton.CustomBackgroundXxx properties change from TCastleImage to TCastleImagePersistent. Instead of assigning them like

  MyButton.CustomBackgroundNormal := LoadImage('castle-data:/my_image.png');
  MyButton.OwnsCustomBackgroundNormal := true;

  MyButton.CustomBackgroundNormal.URL := 'castle-data:/my_image.png';

  MyButton.CustomBackgroundNormal.Image := LoadImage('castle-data:/my_image.png');
  MyButton.CustomBackgroundNormal.OwnsImage := true; // actually this is no longer needed

The callback TAdClosedEvent (used by TAds.OnFullScreenAdClosed) parameters changed.

If you use sounds XML file with importance note that the default value of default_importance is now 10 (not maximum 2147483647). So sounds that had default_importance not explicitly specified are now treated as less important than e.g. default_importance="player". To easily restore previous behavior, just add default_importance="maximum" for sounds without explicit default_importance attribute.

We disabled the default behavior of limiting gravity to only work within the level bounding box. It was non-obvious, and often a trap for newcomers ("why does gravity not work if I jump high?").

  { Don't let objects/camera fall outside of the box because of gravity,
    as then they would fall into infinity. }
  if BecauseOfGravity then
    Allowed := Items.BoundingBox.Contains(NewPosition);

When creating resources from CastleCreatures and CastleItems units, pass SceneManager.LevelProperties as 1st argument, instead of SceneManager.Items.

Since this commit: TShapeNode.Material is now TAbstractMaterialNode, not a more specific TMaterialNode.

  Shape.Material := TMaterialNode.Create; // this still works OK, although is deprecated
  Shape.Material.DiffuseColor := GreenRgb; // this will not compile anymore

  Mat := TMaterialNode.Create;
  Mat.DiffuseColor := GreenRgb;
  Shape.Material := Mat; // deprecated but compiles

  Mat := TMaterialNode.Create;
  Mat.DiffuseColor := GreenRgb;

  Appearance := TAppearanceNode.Create;
  Appearance.Material := Mat;

  Shape.Appearance := Appearance;

TCastleSceneManager.OnMoveAllowed callback is removed. You can use TCastleWalkNavigation.OnMoveAllowed instead. Or set invisible colliders to limit the movement.

TCastleViewport by default has FullSize, AutoCamera, AutoNavigation set to false. Set them to true to have exact behavior from previous engine versions.

The management of levels and player in CastleLevels, CastlePlayer was upgraded in a few ways. In particular, you should now never add Player instance manually to Viewport.Items (so do not call Viewport.Items.Add(Player) yourself). Also, always assign TLevel.Player before calling TLevel.Load.

TCastleTransform.DefaultOrientation changed from otUpYDirectionMinusZ to otUpYDirectionZ. Reason:

Some CastleCameras properties were still in degrees (while the majority of engine used radians for angles). They were changed to be in radians. You may need to update your constants/limits. This affects MouseLookHorizontalSensitivity, MouseLookVerticalSensitivity, RotationHorizontalSpeed, RotationVerticalSpeed.

TPlayer.Navigation is now TCastleMouseLookNavigation instance, not TCastleWalkNavigation instance. That’s because TPlayer.Navigation is now a function, it can return either TPlayer.WalkNavigation (TCastleWalkNavigation instance) or TPlayer.ThirdPersonNavigation (TCastleThirdPersonNavigation instance).

TCastleTransform.PointingDeviceActivate has been removed, and replaced by 2 events TCastleTransform.PointingDevicePress, TCastleTransform.PointingDeviceRelease. They also get additional information as an argument Pick: TRayCollisionNode which allows you to e.g. instantly see what shape (what material etc.) was clicked, if your scene had detailed collisions (Spatial includes ssDynamicCollisions). Like this:

function TMyScene.PointingDevicePress(
  const Pick: TRayCollisionNode; const Distance: Single): Boolean;
begin
  Result := inherited;
  if Result then Exit;

  WritelnLog('Pressed pointing device');
  if (Pick.Triangle <> nil) and
     (Pick.Triangle^.MaterialInfo <> nil) then
    WritelnLog('Pressed on material ' + Pick.Triangle^.MaterialInfo.Node.X3DName);
end;

The RenderContext singleton and related types has been moved to CastleRenderContext unit. Add it to your uses clause, if necessary.

Some enumerated types have been moved to CastleRenderOptions. Add it to your uses clause, if necessary.

Do not use CastleRenderer unit anymore. It contained a lot of internal things, which are now moved to CastleInternalRenderer. The only important feature there were rendering attributes, now in unit CastleRenderOptions. The CastleRenderer unit is now only a skeleton for backward-compatibility.

NewGLUQuadric and CastleGluSphere are removed. These were "thin" wrappers over libGLU quadric routines, and we no longer use libGLU. They have been marked "deprecated" since a long time, and they never worked on mobile.

TCastleTransform.Press, TCastleTransform.Release are now only called when TCastleTransform.ListenPressRelease is true.

TLevelLogic is now TCastleBehavior descendant. Overriding TLevelLogic.Create and TLevelLogic.Update still has the same effect though, so you may not notice much difference. Note that TLevelLogic instance is not yet part of the world when TLevelLogic.Create happens (override TLevelLogic.ParentChanged to do something once it’s part of level; we may introduce event like WorldChanged if necessary too).

The speed of movement in case of TCastleExamineNavigation with orthographic projection and standard dir/up (+Z/+Y) is now more natural. You can revert to previous behavior by setting TCastleExamineNavigation.ExactMovement to false.

TCastleFont is now TCastleAbstractFont, and TTextureFont is now TCastleFont. If you use TCastleFont class name explicitly, this affects you. Now:

We used to support randomization in sounds XML file:

  <?xml version="1.0"?>
  <sounds>
    <alias name="random_test_sound">
      <target name="test_sound_1" />
      <target name="test_sound_2" />
      <target name="test_sound_3" />
    </alias>
  </sounds>

  function BulletSound: TCastleSound;
  begin
    case Random(3) of
      0: Result := SoundBullet1;
      1: Result := SoundBullet2;
      2: Result := SoundBullet3;
    end;
  end;

TCastleUserInterface.LocalToScreenPosition was removed, as both the word "local" (was actually implemented as meaning "parent coordinate system", not local) and "screen" (was actually meaning "container") were confusing. Use LocalToContainerPosition, Parent.LocalToContainerPosition, ContainerToLocalPosition, Parent.ContainerToLocalPosition depending on needs.

We made some changes to vectors. X, Y, Z, W are now fields, and setting them is the only non-deprecated way to modify the vector "in place". See https://castle-engine.io/wp/2022/02/11/vectors-changes-to-avoid-a-trap-with-modifying-a-temporary-value/ .

We had to remove some hacky ways to make things non-existing:

T3DResource is now a descendant of TComponent, and inherits a virtual constructor constructor Create(AOwner: TComponent);. If you were overriding old constructor constructor Create(const AName: string);, you need to change the parameter. Outside code sets Name later, after construction.

CastleRenderingCamera unit and RenderingCamera singleton no longer exist. Access rendering camera only during rendering, using RenderParams.RenderingCamera (RenderParams is a parameter passed to TCastleTransform.LocalRender). Outside of rendering, you only have usual camera in MyViewport.Camera (accessible in TCastleTransform as World.MainCamera).

If you use CastleLevels and friends, note that all creatures are now under Level.CreaturesRoot group (not directly in Viewport.Items; instead, the Level.CreaturesRoot is in Viewport.Items). Similarly all items are in Level.ItemsRoot. This matters if you iterated manually over Viewport.Items searching for some creature/item.

We had to break some compatibility when introducing new cameras and navigation. See https://castle-engine.io/wp/2022/07/09/huge-update-to-cameras-navigation-viewports-in-2d-and-3d/ and https://castle-engine.io/wp/2022/05/06/camera-and-navigation-rework-almost-finished-todo-this-news-announcement-is-too-long-we-have-too-much-new-stuff-to-announce/ .