public abstract class TiledReader extends Object
The TiledReader class is the main class of the TiledReader library, and the library's means of accessing Tiled files. Instances of TiledReader have methods that read Tiled maps, tilesets, object templates, and object types from specified files.
A TiledReader stores a pointer to a set of object types, represented as an
instance of the TiledObjectTypes class. It uses this information to determine
the default values of the custom properties of any Tiled objects and tileset
tiles that it reads, as an implementation of Tiled's "Object Types Editor"
feature. A TiledReader's set of object types can be replaced manually, and a
TiledReader can read new sets of object types from the XML files in which
Tiled stores them. Tiled's default, global object types file is called
objecttypes.xml
, and its location may depend on your operating
system.
A TiledReader stores a cache of pointers to the maps, tilesets, and object templates corresponding to all of the files it has read, which is indexed by canonical (absolute and unique) paths to those files. A TiledReader uses this cache to return the very same resource object if asked to read the same file multiple times. This is mainly to ensure that, if multiple Tiled maps reference the same external tileset or object template file, the external file will not be wastefully parsed and stored in memory multiple times. However, a TiledReader also contains methods that can be called manually to remove pointers from the cache. Removing the pointer to a no-longer-needed resource object is necessary to make the object vulnerable to the Java garbage collector.
The TiledReader class contains abstract methods that perform back-end tasks like I/O and interaction with the resource cache. These methods are implemented in the subclass FileSystemTiledReader, and can be implemented in other ways in custom subclasses.
The TiledReader library does not support image data embedded directly in TMX/TSX files. As of Tiled version 1.4.1, however, it is not possible to embed image data in files using the Tiled editor.
The TiledReader library also ignores information in Tiled files pertaining to deprecated or unsupported features of Tiled. These include the x and y attributes of tile layers, object layers, and image layers (not to be confused with the rendering x and y offsets, which are supported), as well as the width and height attributes of object layers.
For details on the structure and content of Tiled files, see the official Tiled documentation on the subject.
Modifier and Type | Field and Description |
---|---|
static Logger |
LOGGER
The logger for the TiledReader library.
|
static String |
TILED_VERSION
The version number of Tiled that this version of TiledReader was designed
for.
|
static String |
TMX_VERSION
The version of the TMX file format that this version of TiledReader was
designed for.
|
static String |
VERSION
The version number of TiledReader.
|
Constructor and Description |
---|
TiledReader()
Constructs a new TiledReader.
|
Modifier and Type | Method and Description |
---|---|
protected abstract void |
clearCachedResources()
Clears the cache, causing it to no longer identify any resource by any
path.
|
void |
clearResources()
Removes all of this TiledReader's cached pointers to resources that it
has read from files.
|
abstract TiledResource |
getCachedResource(String path)
Returns the resource in the cache identified by the specified path, which
must be a canonical path by the standards of getCanonicalPath().
|
abstract String |
getCanonicalPath(String path)
Returns a version of the specified path string that is both absolute and
unique.
|
abstract InputStream |
getInputStream(String path)
Returns an InputStream that reads the file data at the location of the
specified path, which must be a canonical path by the standards of
getCanonicalPath().
|
TiledMap |
getMap(String path)
Reads a Tiled map from the specified TMX file and returns it as a
TiledMap object.
|
TiledObjectTypes |
getObjectTypes()
Returns this TiledReader's set of object types.
|
TiledObjectTemplate |
getTemplate(String path)
Reads a Tiled object template from the specified TX file and returns it
as a TiledObjectTemplate object.
|
TiledTileset |
getTileset(String path)
Reads a Tiled tileset from the specified TSX file and returns it as a
TiledTileset object.
|
abstract String |
joinPaths(String basePath,
String relativePath)
Returns a path string that points to the same location as the specified
relative path does when followed from the location of the specified base
path.
|
TiledObjectTypes |
readObjectTypes(String path)
Reads the set of object types from the specified object types XML file
and returns it as a TiledObjectTypes object.
|
protected abstract void |
removeCachedResource(String path)
Sets the cache to no longer identify any resource by the specified path,
which must be a canonical path by the standards of getCanonicalPath().
|
boolean |
removeResource(String path,
boolean cleanUp)
Removes this TiledReader's cached pointer to the resource it read from
the specified file, if it has read that file before.
|
protected abstract void |
setCachedResource(String path,
TiledResource resource)
Sets the cache to identify the specified resource by the specified path,
which must be a canonical path by the standards of getCanonicalPath().
|
void |
setObjectTypes(TiledObjectTypes objectTypes)
Sets this TiledReader's set of object types to the specified value.
|
public static final String VERSION
public static final String TILED_VERSION
public static final String TMX_VERSION
public static final Logger LOGGER
public abstract String getCanonicalPath(String path)
java.io.File.getCanonicalPath()
.path
- The path to find the canonical version ofpublic abstract String joinPaths(String basePath, String relativePath)
java.nio.file.Path.resolve()
.basePath
- The base pathrelativePath
- The relative pathpublic abstract InputStream getInputStream(String path)
path
- The canonical path to the file datapublic abstract TiledResource getCachedResource(String path)
path
- The canonical path to the file from which the resource was
readprotected abstract void setCachedResource(String path, TiledResource resource)
path
- The canonical path by which to identify the resourceresource
- The resource to be identified by the pathprotected abstract void removeCachedResource(String path)
path
- The canonical path that identifies the resource to remove
from the cacheprotected abstract void clearCachedResources()
public final TiledObjectTypes getObjectTypes()
public final void setObjectTypes(TiledObjectTypes objectTypes)
objectTypes
- This TiledReader's new set of object types. If this is
null, this TiledReader will ave no object types.public final TiledObjectTypes readObjectTypes(String path)
path
- The path to the object types file to readpublic final TiledMap getMap(String path)
path
- The path to the TMX file to readpublic final TiledTileset getTileset(String path)
path
- The path to the TSX file to readpublic final TiledObjectTemplate getTemplate(String path)
path
- The path to the TX file to readpublic final boolean removeResource(String path, boolean cleanUp)
path
- The path to the file to forget aboutcleanUp
- If true, also remove the cached pointers to all of the
resources referenced by the resource from the specified file, and not
referenced by any of the other resources that this TiledReader still
remembers. This parameter applies recursively, so if the removal of any
of these "orphaned" resources causes more resources to be orphaned, those
will be removed as well.public final void clearResources()
Copyright © 2020. All rights reserved.