Class TLevelInfo

Unit

Declaration

type TLevelInfo = class(TObject)

Description

Hierarchy

  • TObject
  • TLevelInfo

Overview

Fields

Protected Element: TDOMElement;

Methods

Public constructor Create;
Public destructor Destroy; override;

Properties

Public property LogicClass: TLevelLogicClass read FLogicClass write FLogicClass;
Public property Name: string read FName write FName;
Public property SceneURL: string read FSceneURL write FSceneURL;
Public property SceneFileName: string read FSceneURL write FSceneURL; deprecated;
Public property Title: string read FTitle write FTitle;
Public property TitleHint: string read FTitleHint write FTitleHint;
Public property Number: Integer read FNumber write FNumber default 0;
Public property Demo: boolean read FDemo write FDemo default false;
Public property Played: boolean read FPlayed write FPlayed;
Public property DefaultPlayed: boolean read FDefaultPlayed write FDefaultPlayed;
Public property LoadingImage: TRGBImage read FLoadingImage write FLoadingImage;
Public property LoadingBarYPosition: Single read FLoadingBarYPosition write FLoadingBarYPosition default TProgressUserInterface.DefaultBarYPosition;
Public property PlaceholderName: TPlaceholderName read FPlaceholderName write FPlaceholderName;
Public property PlaceholderReferenceDirection: TVector3 read FPlaceholderReferenceDirection write FPlaceholderReferenceDirection;
Public property MusicSound: TSoundType read FMusicSound write FMusicSound;

Description

Fields

Protected Element: TDOMElement;
 

Methods

Public constructor Create;
 
Public destructor Destroy; override;
 

Properties

Public property LogicClass: TLevelLogicClass read FLogicClass write FLogicClass;

Level logic class. This is indicated by the "type" attribute in level.xml file. By default level logic uses a base TLevelLogic class, which corresponds to using type="Level" in level.xml file.

Changing this allows to use a different ObjectPascal class to implement the level behavior. You can create your own TLevelLogic descendants and register them like

type
  TMyLevelLogic = class(TLevelLogic)
    { ... override whatever you want ... }
  end;

...
LevelLogicClasses['MyLevel'] := TMyLevelLogic;

And then you can use type="MyLevel" inside level.xml to use your class. Many advanced tricks are possible by implementing your own TLevelLogic descendant. See Castle1 GameLevelSpecific.pas unit for some examples.

Public property Name: string read FName write FName;

Unique identifier of this level. This name may be useful in scripts, as TGameSceneManager.LoadLevel parameter and such.

For all (current and future) uses it should be a valid VRML/X3D and ObjectPascal identifier, so use only (English) letters, underscores and digits (and don't start with a digit).

Public property SceneURL: string read FSceneURL write FSceneURL;

Main level 3D model. When the level is loaded, this scene will be set as TCastleSceneManager.MainScene, so it determines the default viewpoint, background and such.

Usually it also contains the most (if not all) of the visible level geometry, scripts and such. Although level logic (TLevelLogic descendant determined by LevelClass) may also add any number of additional objects (TCastleTransform instances) to the world.

Public property SceneFileName: string read FSceneURL write FSceneURL; deprecated;

Warning: this symbol is deprecated.

Deprecated name for SceneURL.

Public property Title: string read FTitle write FTitle;

Nice name of the level for user. This should be user-friendly, so it can use spaces, non-English letters and such.

The core engine (like this CastleLevels unit) doesn't use this title much, it's only for progress bars and log messages.

It is up to the final game code to use this title in more interesting ways. For example to show a choice of starting level to the user. The core engine doesn't make such "New Game" menus automatically (because various games may have widly different ideas how to make it and how to show it). But we give the developer tools to make such menus easily, for example you can use TCastleOnScreenMenu for this.

Public property TitleHint: string read FTitleHint write FTitleHint;

Additional text that may be displayed near level title.

The engine doesn't use this property at all, it's only loaded from level.xml file. It is available for your "New Game" (or similar screen) implementation (see Title for more comments about this).

Public property Number: Integer read FNumber write FNumber default 0;

Level number.

The engine doesn't use this property at all, it's only loaded from level.xml file. It is available for your "New Game" (or similar screen) implementation (see Title for more comments about this).

For example level number may be used to order levels in the menu. This does not determine the order in which levels are played, as levels do not have to be played in a linear order.

Public property Demo: boolean read FDemo write FDemo default false;

Is it a demo level.

The engine doesn't use this property at all, it's only loaded from level.xml file. It is available for your "New Game" (or similar screen) implementation (see Title for more comments about this).

Public property Played: boolean read FPlayed write FPlayed;

Was the level played.

This is automatically managed. Basically, we set it to True when the level is played, and we save it to user preferences.

Details:

  • It is set to True when loading level.

  • It is saved to disk (user preferences file) when game exits, and loaded when game starts. As long as you call Config.Load, Config.Save from CastleConfig unit. To load, you must also call explicitly Levels.LoadFromConfig now.

  • The default value comes from DefaultPlayed property, which in turn is loaded from level.xml file, and by default is False. To allows you to artificially mark some levels as "Played" on the first game run, which may be helpful if you use this property e.g. to filter the levels in "New Game" menu.

The engine doesn't look at this property for anything, whether the level is played or not has no influence over how we work. It is just available for your game, for example to use in your "New Game" (or similar screen) implementation (see Title for more comments about this).

Public property DefaultPlayed: boolean read FDefaultPlayed write FDefaultPlayed;

Should the level be initially considered "played". This determines the initial value of Played property (if nothing was stored in user preferences about this level, see TLevelInfoList.LoadFromConfig; or if TLevelInfoList.LoadFromConfig is not called by the game).

How is this information useful, depends on a particular game. For example, some games may decide to show in the "New Game" menu levels only with Played=true. Some games may simply ignore it.

Public property LoadingImage: TRGBImage read FLoadingImage write FLoadingImage;

Background image shown when loading the level, Nil if none. This is loaded from URL indicated by attribute loading_image in level.xml.

Public property LoadingBarYPosition: Single read FLoadingBarYPosition write FLoadingBarYPosition default TProgressUserInterface.DefaultBarYPosition;

Vertical position of progress bar when loading the level. Between 0 and 1, default value 0.5 means "middle of the screen". Should be synchronized with how LoadingImage looks (if you set it), to make the progress when loading level look nice.

Technically, this is used for TProgressUserInterface.BarYPosition.

Public property PlaceholderName: TPlaceholderName read FPlaceholderName write FPlaceholderName;

Placeholder detection method. See TPlaceholderName, and see TGameSceneManager.LoadLevel for a description when we use placeholders. Default value is PlaceholderNames['x3dshape'].

Public property PlaceholderReferenceDirection: TVector3 read FPlaceholderReferenceDirection write FPlaceholderReferenceDirection;

How to interpret the placeholders direction (like the initial creature direction on the level). Some placeholders (currently, only creatures) may be used to determine initial direction of the resource. For example, the direction the creature is initially facing. This direction is calculated as the transformation of given placeholder applied to this 3D vector.

The correct value may depend on the exporter you used to create 3D models, and on the exporter settings (how and if it rotates the model when exporting, and is this rotation recorded in placeholder transformation or applied directly to mesh coordinates). It may also depend on personal preference, as it determines how you set resources in your 3D modelling tool (like Blender).

Fortunately, the default value (+X vector) is suitable for at least 2 common situations:

  1. If your exporter rotates the world to turn +Z up into +Y up. (This is the case of default Blender X3D exporter with default settings.)

  2. If your exporter doesn't rotate the world. (You can configure Blender exporter to behave like this. You may also then configure engine to use +Z as up vector for everything, see "Which way is up?" on [https://castle-engine.io/tutorial_up.php].)

In Blender it's useful to enable the "Display -> Wire" option for placeholder objects, then Blender will show arrows inside the placeholder. +X of the arrow determines the default direction understood by our engine.

Public property MusicSound: TSoundType read FMusicSound write FMusicSound;

Music played when entering the level. None (stNone) by default.


Generated by PasDoc 0.15.0.