TCastleWindow.SceneManager: removal of a deprecated property soon

News
1
Castle Game Engine example - multiple_viewports

As we extend the engine, we sometimes have to deprecate some old features, that were not very useful, and sometimes prevented the engine API from being flexible and easy to understand.

One of these things was TCastleSceneManager class (renamed to TCastleViewport since 2 years), with its single “central” instance in TCastleWindow.SceneManager or TCastleControl.SceneManager. In a hindsight, I know it was a mistake to add such “central” reference to “one main scene manager”. It was much better to focus on adding multiple UI controls to your window (which we did), and realizing that various scenarios are possible:

  • Some games don’t need TCastleSceneManager / TCastleViewport at all.

    E.g. applications with simple UI, where everything is just a simple 2D UI control.

  • Some games need one instance of TCastleSceneManager / TCastleViewport (e.g. typical 3D FPS games). But it still may not exist always, so it better exists only within particular TUIState.

  • Some games need more instances of TCastleSceneManager / TCastleViewport. Maybe on one TUIState (e.g. split-screen local multiplayer games), maybe spread in many TUIState instances (e.g. 3D game view, 3D map view etc.).

This observation led to the API you now have and use. But… the TCastleWindow.SceneManager and TCastleControl.SceneManager are still defined, for backward compatibility. And we advise everyone to use classes with Base suffix, TCastleWindowBase and TCastleControlBase, to avoid having this “automatic central scene manager” present. This is causing complicated engine code (for backward compatibility), complicated docs (why the Base suffix?), and unnecessary dependencies in CastleWindow unit (that right now has to depend on almost all CGE code, as TCastleSceneManager / TCastleViewport depends on TCastleScene that depends on almost everything else).

We had TCastleWindow.SceneManager and TCastleControl.SceneManager deprecated for 2 years now, since December 2019. Time to actually remove them 🙂 So, a plea: if you use TCastleWindow or TCastleControl, if you see messages that they are deprecated but you keep using them anyway… stop 🙂

The best way to upgrade is to switch to using TUIState, designed by CGE editor, and put TCastleViewport in your games this way. But as a last resort, you can even create local copy of existing TCastleWindow code from castlewindow.pas, it isn’t long.

At the end of January 2022 (in 1 month) we will actually remove TCastleWindow.SceneManager and TCastleControl.SceneManager. The TCastleWindow and TCastleControl will become equivalent to their ...Base counterparts, and we will encourage to use again the simpler names (as there will be no point in using ...Base suffix). It is easy to try it right now: go to src/common_includes/castleconf.inc, find

{$ifdef FPC}
  {$define CASTLE_DEPRECATED_WINDOW_CLASSES}
{$endif}

and just remove it. Or add something, e.g. dot, to make the {$define CASTLE_DEPRECATED_WINDOW_CLASSES} inactive, like this:

{$ifdef FPC}
  {.$define CASTLE_DEPRECATED_WINDOW_CLASSES}
{$endif}

This will change the TCastleWindow and TCastleControl to be equivalent to their ...Base counterparts, without any deprecated SceneManager property.

Please support the engine development on our Patreon. It funds development of the engine, it means we have resources to design the engine the right way!

1 Like