Class TCastleTiledMapControl

Unit

Declaration

type TCastleTiledMapControl = class(TCastleUserInterface)

Description

Display a map created in Tiled (https://www.mapeditor.org/).

Hierarchy

Overview

Methods

Public constructor Create(AOwner: TComponent); override;
Public destructor Destroy; override;
Public procedure Render; override;
Public function PropertySection(const PropertyName: String): TPropertySection; override;
Public procedure LoadFromFile(const AURL: string); deprecated 'set URL instead of calling LoadFromFile';
Public function PositionToTile(const Position: TVector2; const ScreenCoordinates: Boolean; out TilePosition: TVector2Integer): Boolean;
Public function TileRectangle(const TilePosition: TVector2Integer; const ScreenCoordinates: Boolean): TFloatRectangle; overload;
Public function TileRectangle(const TilePosition: TVector2Integer; const ScreenCoordinates: Boolean; const ForceTileWidth, ForceTileHeight: Single): TFloatRectangle; overload;

Properties

Public property Origin: TVector2 read FOrigin write SetOrigin;
Public property Map: TTiledMap read FMap;
Published property ClipChildren default true;
Published property URL: String read FURL write SetURL;
Published property Scale: Single read FScale write SetScale default 1;
Published property SmoothScaling: Boolean read FSmoothScaling write SetSmoothScaling default false;
Published property SmoothScalingSafeBorder: Boolean read FSmoothScalingSafeBorder write SetSmoothScalingSafeBorder default false;
Published property OriginPersistent: TCastleVector2Persistent read FOriginPersistent ;

Description

Methods

Public constructor Create(AOwner: TComponent); override;
 
Public destructor Destroy; override;
 
Public procedure Render; override;
 
Public function PropertySection(const PropertyName: String): TPropertySection; override;
 
Public procedure LoadFromFile(const AURL: string); deprecated 'set URL instead of calling LoadFromFile';

Warning: this symbol is deprecated: set URL instead of calling LoadFromFile

Load given TMX file to memory and creates structures.

Public function PositionToTile(const Position: TVector2; const ScreenCoordinates: Boolean; out TilePosition: TVector2Integer): Boolean;

Detect tile under given position.

The interpretation of Position depends on ScreenCoordinates:

  • When ScreenCoordinates = True, then Position is relative to the whole container (like TCastleWindow or TCastleControl).

    And it is expressed in real device coordinates, just like TInputPressReleaseEvent.Position when mouse is being clicked, or like TInputMotionEvent.Position when mouse is moved.

  • When ScreenCoordinates = False, then Position is relative to this UI control.

    And it is expressed in coordinates after UI scaling. IOW, if the size of this control is Width = 100, then Position.X between 0 and 100 reflects the visible range of this control.

Note that you can query the positions that are outside of this UI control, or even outside of the container. They will return correct map tiles, as if the map was rendered there. If you want to avoid this, you can e.g. check whether Position is inside the RenderRect (if it's a position in screen coordinates, with ScreenCoordinates = True).

This method returns False if the position is outside of the map. Valid map tiles are from (0, 0) (lower-left) to (TTiledMap.Width - 1, TTiledMap.Height - 1) (upper-right).

Public function TileRectangle(const TilePosition: TVector2Integer; const ScreenCoordinates: Boolean): TFloatRectangle; overload;

Rectangle where the given map tile is rendered. Useful to render something over a TCastleTiledMapControl, e.g. a pawn in a game.

In some way, this method is an inverse of the PositionToTile method. It converts map (tile) coordinates back into coordinates useful to display something. The ScreenCoordinates value determines the coordinate system of the resulting rectangle. It's meaning is similar to the ScreenCoordinates parameter of the PositionToTile method.

This method works for any TilePosition, even outside of valid map positions. Returns TFloatRectangle.Empty is Map not loaded (URL not set).

Some maps may use tilesets in which image size is different than map tile size. That is, TTiledMap.TTileset.TileWidth may be different than TTiledMap.TileWidth for some tilesets. The simpler version of this method, without ForceTileWidth/Height, just returns the size of the map tile looking at (TTiledMap.TileWidth, TTiledMap.TileHeight), since it doesn't know the tileset you use.

You can pass ForceTileWidth and ForceTileHeight to set particular size.

Public function TileRectangle(const TilePosition: TVector2Integer; const ScreenCoordinates: Boolean; const ForceTileWidth, ForceTileHeight: Single): TFloatRectangle; overload;
 

Properties

Public property Origin: TVector2 read FOrigin write SetOrigin;

Origin determines the map position at control's left-bottom corner. Increasing Origin.X moves visually the map to the left, increasing Origin.Y moves it down.

Public property Map: TTiledMap read FMap;

Currently loaded map (from URL), if any. Nil if no map is loaded (when URL is empty). Read-only.

Published property ClipChildren default true;
 
Published property URL: String read FURL write SetURL;

URL (or just filename) of the Tiled map file (TMX).

Published property Scale: Single read FScale write SetScale default 1;
 
Published property SmoothScaling: Boolean read FSmoothScaling write SetSmoothScaling default false;

How are images scaled (because of UI scaling, because of Scale). True means we use nice "bilinear" filter. False means we use pixelated "nearest" filter.

Beware that using True, and scaling the map, requires preparing the tileset (atlas of tile images) in a proper way. The space around each tile must have at least 1-pixel margin filled with the same color and alpha ("color bleeding"), otherwise bad colors will creep in because of bilinear filtering. Alternatively, you can use SmoothScalingSafeBorder.

Published property SmoothScalingSafeBorder: Boolean read FSmoothScalingSafeBorder write SetSmoothScalingSafeBorder default false;

In case of SmoothScaling, prevent the color outside of rendered frame from creeping in, by stretching the rendered frame a bit. See TSprite.SmoothScalingSafeBorder.

It is better to prepare the sprite (tileset) images with some spacing between tiles, and color bleeding, instead of using this property. This property workarounds the fact that some sprite (tileset) images lack proper spacing and color bleeding, but it distorts the image a bit, so it's no longer pixel-perfect.

Published property OriginPersistent: TCastleVector2Persistent read FOriginPersistent ;

Origin that can be visually edited in Castle Game Engine Editor, Lazarus and Delphi. Normal user code does not need to deal with this, instead read or write Origin directly.

See also
Origin
Origin determines the map position at control's left-bottom corner.

Generated by PasDoc 0.15.0.