Class TLevel

Load game level.

• Set Viewport.Items:

  Clear TCastleViewport.Items, clear Navigation, clear TCastleRootTransform.MainScene as well. Then load a new main scene and set navigation, adding to TCastleViewport.Items all resources (creatures and items) defined by placeholders named CasRes* in the main level file.

• Make sure resources are ready:

  Resources are T3DResource instances on Resources list. They are heavy (in terms of memory use and preparation time), so you don't want to just load everything for every level. This method makes sure that all resources required by this level are prepared. All resources requested in level.xml file (in <resources> element in level.xml), as well as resources requested in player.xml file, as well as resources with AlwaysPrepared (usually: all possible items that can be dropped from player inventory on any level) will be prepared.

• Initialize move limits and water volume from placeholders. Special object names CasMoveLimit and CasWater (in the future: CasWater* with any suffix) in the main scene 3D model determine the places where player can go and where water is.

  When CasMoveLimit object is missing, we calculate it to include the level bounding box, with some additional space above (to allow flying).

• Initialize sectors and waypoints from placeholders. Special shape names CasSector* and CasWaypoint* can be used in level 3D model to help creature AI. You can add and name such shapes in 3D modeler, like Blender, and they will be automatically understood by the engine when loading level.

  Objects named CasSector<index>[_<ignored>] define sectors. The geometry of a sector with given <index> is set to be the sum of all CasSector<index>* boxes. Sectors are numbered from 0.

  Objects named CasWaypoint[<ignored>] define waypoints. Each waypoint is stored as a 3D point, this point is the middle of the bounding box of the object named CasWaypoint[<ignored>].

  After extracting from level 3D model, sectors and waypoints are then connected together by TSectorList.LinkToWaypoints. The idea is that you can go from one sector to the other through the waypoint that is placed on the border of both of them.

• Prepare everything possible for rendering and collision detection to avoid later preparing things on-demand (which would cause unpleasant delay during gameplay).

The overloaded version with a LevelName string searches the Levels list for a level with given name (and raises exception if it cannot be found). It makes sense if you filled the Levels list before, usually by Levels.LoadFromFiles call. So you can easily define a level in your data with name="xxx" in the level.xml file, and then you can load it by Load('xxx') call.

It's important to note that you do not have to use this method to make a 3D game. You may as well just load the 3D scene yourself, and add things to TCastleViewport.Items and TCastleRootTransform.MainScene directly. This method is just a comfortable way to set a world, with creatures and items, using placeholders.

Release everything loaded by Load, clearing the 3D world.

You do not have to call this in normal circumstances, as each Load automatically clears previous 3D world. If fact, you should not call this in normal circumstances: calling this prevents the next Load to reuse resources that were needed by both old and new level.

Call this only if you really want to conserve memory right now. Or when you want to force reload of resources at next Load call (for example, if you changed BakedAnimationSmoothness, it is useful — otherwise the old animations will remain loaded with old BakedAnimationSmoothness setting).

Viewport whose contents will be adjusted to show given level. Must be assigned before Load.

Level logic and state.

Level information, independent from current level state.

Sectors and waypoints of this world, for AI in 3D. Initialized by Load. Nil if you never call Load.

Water volume in the scene. It may be used by various 3D objects to indicate appropriate behavior — some things swim, some things drown and such. For now, this is only used by TPlayer class to detect swimming (and make appropriate sounds, special rendering, drowning and such).

For now, this is just a simple TBox3D. It will be extended to represent a set of flexible 3D volumes in the future.

Empty initially. Initialize it however you want.

Player in this 3D world. This serves various purposes:

• This object never collides with the navigation. See TCastleViewport.AvoidNavigationCollisions.

• Player transformation will be automatically synchronized with current TCastleViewport.Camera position. As such, TPlayer represents the volume of player in 1st person games.

• For AI in CastleCreatures, hostile creatures will attack this player. So this determines the target position that creatures try to reach, where they shoot missiles etc. More advanced AI, with friendlies/companions, or cooperating factions of creatures, may have other mechanisms to determine who wants to attack who.

• For items on level in CastleItems, this player will pick up the items lying on the ground, and will be able to equip weapons. This functionality may be generalized in the future, to allow anyone to pick up and carry and equip items.