diff --git a/litiengine/src/main/java/de/gurkenlabs/litiengine/resources/Blueprints.java b/litiengine/src/main/java/de/gurkenlabs/litiengine/resources/Blueprints.java index 0ad06a2ba..6f91476c9 100644 --- a/litiengine/src/main/java/de/gurkenlabs/litiengine/resources/Blueprints.java +++ b/litiengine/src/main/java/de/gurkenlabs/litiengine/resources/Blueprints.java @@ -9,16 +9,35 @@ import de.gurkenlabs.litiengine.util.io.FileUtilities; import de.gurkenlabs.litiengine.util.io.XmlUtilities; +/** + * A class that manages the loading and handling of Blueprint resources. + */ public class Blueprints extends ResourcesContainer { + /** + * Constructs a new Blueprints container. + */ Blueprints() {} + /** + * Checks if the given file name is supported by this container. + * + * @param fileName The name of the file to check. + * @return true if the file is supported, false otherwise. + */ public static boolean isSupported(String fileName) { String extension = FileUtilities.getExtension(fileName); - return extension != null && !extension.isEmpty() - && (extension.equalsIgnoreCase(Blueprint.BLUEPRINT_FILE_EXTENSION) || extension.equalsIgnoreCase(Blueprint.TEMPLATE_FILE_EXTENSION)); + return !extension.isEmpty() && (extension.equalsIgnoreCase(Blueprint.BLUEPRINT_FILE_EXTENSION) || extension.equalsIgnoreCase( + Blueprint.TEMPLATE_FILE_EXTENSION)); } + /** + * Loads a Blueprint resource from the specified URL. + * + * @param resourceName The URL of the resource to load. + * @return The loaded Blueprint resource. + * @throws Exception if an error occurs while loading the resource. + */ @Override protected Blueprint load(URL resourceName) throws Exception { Blueprint blueprint; @@ -31,6 +50,13 @@ protected Blueprint load(URL resourceName) throws Exception { return blueprint; } + /** + * Gets the alias for the specified resource. + * + * @param resourceName The name of the resource. + * @param resource The resource to get the alias for. + * @return The alias of the resource, or null if no alias is available. + */ @Override protected String getAlias(String resourceName, Blueprint resource) { if (resource == null || resource.getName() == null || resource.getName().isEmpty() || resource.getName().equalsIgnoreCase(resourceName)) { diff --git a/litiengine/src/main/java/de/gurkenlabs/litiengine/resources/DataFormat.java b/litiengine/src/main/java/de/gurkenlabs/litiengine/resources/DataFormat.java index 0e8808d80..695f2f862 100644 --- a/litiengine/src/main/java/de/gurkenlabs/litiengine/resources/DataFormat.java +++ b/litiengine/src/main/java/de/gurkenlabs/litiengine/resources/DataFormat.java @@ -1,17 +1,25 @@ package de.gurkenlabs.litiengine.resources; -import java.util.ArrayList; - import de.gurkenlabs.litiengine.util.io.FileUtilities; +import java.util.ArrayList; /** - * Some common implementations that are used by different kinds of file classes (e.g. {@code SoundFormat}, - * {@code ImageFormat}. + * Some common implementations that are used by different kinds of file classes (e.g. {@code SoundFormat}, {@code ImageFormat}. */ final class DataFormat { - private DataFormat() {} + private DataFormat() { + } - protected static > T get(String format, T[] values, T defaultValue) { + /** + * Retrieves the enum value corresponding to the given format string. + * + * @param The type of the enum. + * @param format The format string to match. + * @param values The array of enum values to search. + * @param defaultValue The default value to return if no match is found. + * @return The matching enum value, or the default value if no match is found. + */ + static > T get(String format, T[] values, T defaultValue) { if (format == null || format.isEmpty()) { return defaultValue; } @@ -30,9 +38,18 @@ protected static > T get(String format, T[] values, T defaultV return defaultValue; } - protected static > boolean isSupported(String fileName, T[] values, T defaultValue) { + /** + * Checks if the given file name is supported by the specified enum values. + * + * @param The type of the enum. + * @param fileName The name of the file to check. + * @param values The array of enum values to search. + * @param defaultValue The default value to use for comparison. + * @return true if the file is supported, false otherwise. + */ + static > boolean isSupported(String fileName, T[] values, T defaultValue) { String extension = FileUtilities.getExtension(fileName); - if (extension == null || extension.isEmpty()) { + if (extension.isEmpty()) { return false; } @@ -45,7 +62,15 @@ protected static > boolean isSupported(String fileName, T[] va return false; } - protected static > String[] getAllExtensions(T[] values, T defaultValue) { + /** + * Retrieves all extensions for the specified enum values. + * + * @param The type of the enum. + * @param values The array of enum values to search. + * @param defaultValue The default value to exclude from the result. + * @return An array of strings representing all extensions. + */ + static > String[] getAllExtensions(T[] values, T defaultValue) { ArrayList arrList = new ArrayList<>(); for (T format : values) { if (format != defaultValue) { @@ -53,6 +78,6 @@ protected static > String[] getAllExtensions(T[] values, T def } } - return arrList.toArray(new String[arrList.size()]); + return arrList.toArray(new String[0]); } } diff --git a/litiengine/src/main/java/de/gurkenlabs/litiengine/resources/Fonts.java b/litiengine/src/main/java/de/gurkenlabs/litiengine/resources/Fonts.java index 2ec29a882..5222d7434 100644 --- a/litiengine/src/main/java/de/gurkenlabs/litiengine/resources/Fonts.java +++ b/litiengine/src/main/java/de/gurkenlabs/litiengine/resources/Fonts.java @@ -8,11 +8,22 @@ import java.util.logging.Level; import java.util.logging.Logger; +/** + * A container class for managing font resources. This class extends the ResourcesContainer class, specifically for Font objects. + */ public final class Fonts extends ResourcesContainer { private static final Logger log = Logger.getLogger(Fonts.class.getName()); - Fonts() {} + Fonts() { + } + /** + * Retrieves a font with the specified name and size. + * + * @param name The name of the font. + * @param size The size of the font. + * @return The derived font with the specified size, or null if the font is not found. + */ public Font get(String name, float size) { Font font = this.get(name); if (font == null) { @@ -22,6 +33,13 @@ public Font get(String name, float size) { return font.deriveFont(size); } + /** + * Retrieves a font with the specified name and style. + * + * @param name The name of the font. + * @param style The style of the font (e.g., Font.PLAIN, Font.BOLD). + * @return The derived font with the specified style, or null if the font is not found. + */ public Font get(String name, int style) { Font font = this.get(name); if (font == null) { @@ -31,6 +49,14 @@ public Font get(String name, int style) { return font.deriveFont(style); } + /** + * Retrieves a font with the specified name, style, and size. + * + * @param name The name of the font. + * @param style The style of the font (e.g., Font.PLAIN, Font.BOLD). + * @param size The size of the font. + * @return The derived font with the specified style and size, or null if the font is not found. + */ public Font get(String name, int style, float size) { Font font = this.get(name); if (font == null) { @@ -47,7 +73,7 @@ public Font get(String name, int style, float size) { * @param resourceName * The name of the font * @return The loaded font. - * + * * @see Font#createFont(int, java.io.File) * @see Font#getFont(String) */ diff --git a/litiengine/src/main/java/de/gurkenlabs/litiengine/resources/Images.java b/litiengine/src/main/java/de/gurkenlabs/litiengine/resources/Images.java index 664b3d3ae..81eed20e7 100644 --- a/litiengine/src/main/java/de/gurkenlabs/litiengine/resources/Images.java +++ b/litiengine/src/main/java/de/gurkenlabs/litiengine/resources/Images.java @@ -1,22 +1,23 @@ package de.gurkenlabs.litiengine.resources; +import de.gurkenlabs.litiengine.entities.Rotation; +import de.gurkenlabs.litiengine.util.Imaging; import java.awt.image.BufferedImage; import java.io.IOException; import java.net.URL; - import javax.imageio.ImageIO; -import de.gurkenlabs.litiengine.entities.Rotation; -import de.gurkenlabs.litiengine.util.Imaging; - +/** + * A container class for managing image resources. This class extends the ResourcesContainer class, specifically for BufferedImage objects. + */ public final class Images extends ResourcesContainer { - Images() {} + Images() { + } /** * Loads all images from the specified texture atlas. - * - * @param textureAtlas - * The texture atlas that contains all the images. + * + * @param textureAtlas The texture atlas that contains all the images. */ public void load(TextureAtlas textureAtlas) { BufferedImage atlasImage = Resources.images().get(textureAtlas.getAbsoluteImagePath()); @@ -35,12 +36,9 @@ public void load(TextureAtlas textureAtlas) { } /** - * Loads the image by the specified resourceName. This method supports both loading images from a folder and loading - * them from the resources. + * Loads the image by the specified resourceName. This method supports both loading images from a folder and loading them from the resources. * - * @param resourceName - * The path to the image. - * + * @param resourceName The path to the image. * @return the image */ @Override diff --git a/litiengine/src/main/java/de/gurkenlabs/litiengine/resources/Maps.java b/litiengine/src/main/java/de/gurkenlabs/litiengine/resources/Maps.java index a30b92b40..1f8b34b21 100644 --- a/litiengine/src/main/java/de/gurkenlabs/litiengine/resources/Maps.java +++ b/litiengine/src/main/java/de/gurkenlabs/litiengine/resources/Maps.java @@ -1,16 +1,5 @@ package de.gurkenlabs.litiengine.resources; -import java.io.IOException; -import java.net.URISyntaxException; -import java.net.URL; -import java.util.ArrayList; -import java.util.List; -import java.util.function.IntBinaryOperator; -import java.util.logging.Level; -import java.util.logging.Logger; - -import jakarta.xml.bind.JAXBException; - import de.gurkenlabs.litiengine.entities.IEntity; import de.gurkenlabs.litiengine.environment.MapObjectSerializer; import de.gurkenlabs.litiengine.environment.tilemap.IMap; @@ -28,22 +17,41 @@ import de.gurkenlabs.litiengine.graphics.RenderType; import de.gurkenlabs.litiengine.util.io.FileUtilities; import de.gurkenlabs.litiengine.util.io.XmlUtilities; +import jakarta.xml.bind.JAXBException; +import java.io.IOException; +import java.net.URISyntaxException; +import java.net.URL; +import java.util.ArrayList; +import java.util.List; +import java.util.function.IntBinaryOperator; +import java.util.logging.Level; +import java.util.logging.Logger; +/** + * A container class for managing map resources. This class extends the ResourcesContainer class, specifically for IMap objects. + */ public final class Maps extends ResourcesContainer { private static final Logger log = Logger.getLogger(Maps.class.getName()); - Maps() {} + Maps() { + } + /** + * Checks if the specified file name has a supported extension. + * + * @param fileName The name of the file to check. + * @return true if the file has a supported extension, false otherwise. + */ public static boolean isSupported(String fileName) { String extension = FileUtilities.getExtension(fileName); - return extension != null && !extension.isEmpty() && extension.equalsIgnoreCase(TmxMap.FILE_EXTENSION); + return extension.equalsIgnoreCase(TmxMap.FILE_EXTENSION); } /** * Starts a process that allows the generation of maps from code. *

- * Notice that you must call this within a try-with block or ensure that {@link MapGenerator#close()} is called before - * using the generated map instance. + * Notice that you must call this within a try-with block or ensure that {@link MapGenerator#close()} is called before using the generated map + * instance. *

* * Example usage: @@ -71,20 +79,13 @@ public static boolean isSupported(String fileName) { * } * * - * @param orientation - * The orientation of the map to be generated. - * @param name - * The name of the map to be generated. - * @param width - * The width (in tiles). - * @param height - * The height (in tiles). - * @param tileWidth - * The width of a tile (in pixels). - * @param tileHeight - * The height of a tile (in pixels). - * @param tilesets - * Tilesets that will be used by the map. + * @param orientation The orientation of the map to be generated. + * @param name The name of the map to be generated. + * @param width The width (in tiles). + * @param height The height (in tiles). + * @param tileWidth The width of a tile (in pixels). + * @param tileHeight The height of a tile (in pixels). + * @param tilesets Tilesets that will be used by the map. * @return A {@code MapGenerator} instance used to add additional layers or objects to the map. */ public MapGenerator generate(IMapOrientation orientation, String name, int width, int height, int tileWidth, int tileHeight, ITileset... tilesets) { @@ -102,6 +103,14 @@ public MapGenerator generate(IMapOrientation orientation, String name, int width return new MapGenerator(map); } + /** + * Loads an IMap resource from the specified URL. + * + * @param resourceName The URL of the resource to load. + * @return The loaded IMap resource. + * @throws IOException If an I/O error occurs. + * @throws URISyntaxException If the URL is not formatted correctly. + */ @Override protected IMap load(URL resourceName) throws IOException, URISyntaxException { TmxMap map; @@ -144,7 +153,6 @@ private MapGenerator(TmxMap map) { *

* * @return The map generated by this instance. - * * @see #close() */ public IMap getMap() { @@ -168,10 +176,8 @@ public IMap getMap() { * } * * - * @param renderType - * The rendertype of the added layer. - * @param tileCallback - * The callback that defines which tile gid will be assigned at the specified x, y grid coordinates. + * @param renderType The rendertype of the added layer. + * @param tileCallback The callback that defines which tile gid will be assigned at the specified x, y grid coordinates. * @return The newly added tile layer. */ public ITileLayer addTileLayer(RenderType renderType, IntBinaryOperator tileCallback) { @@ -207,9 +213,7 @@ public ITileLayer addTileLayer(RenderType renderType, IntBinaryOperator tileCall * If no layer has been added yet, a default {@code MapObjectLayer} will be created by this method. *

* - * @param entity - * The entity to be converted to a map object and added to the first {@code MapObjectLayer} of the generated - * map. + * @param entity The entity to be converted to a map object and added to the first {@code MapObjectLayer} of the generated map. * @return The created map object. */ public IMapObject add(IEntity entity) { @@ -219,10 +223,8 @@ public IMapObject add(IEntity entity) { /** * Adds a {@code MapObject} created by the specified entity to the map of this instance. * - * @param layer - * The layer to which the map object will be added. - * @param entity - * The entity to be converted to a map object and added to the specified {@code MapObjectLayer}. + * @param layer The layer to which the map object will be added. + * @param entity The entity to be converted to a map object and added to the specified {@code MapObjectLayer}. * @return The created map object. */ public IMapObject add(IMapObjectLayer layer, IEntity entity) { @@ -236,8 +238,7 @@ public IMapObject add(IMapObjectLayer layer, IEntity entity) { * If no layer has been added yet, a default {@code MapObjectLayer} will be created by this method. *

* - * @param mapObject - * The mapObject to be added to the first {@code MapObjectLayer} of the generated map. + * @param mapObject The mapObject to be added to the first {@code MapObjectLayer} of the generated map. * @return The added map object. */ public IMapObject add(IMapObject mapObject) { @@ -256,10 +257,8 @@ public IMapObject add(IMapObject mapObject) { /** * Adds the specified map object to the map of this instance. * - * @param layer - * The layer to which the map object will be added. - * @param mapObject - * The mapObject to be added to the specified {@code MapObjectLayer}. + * @param layer The layer to which the map object will be added. + * @param mapObject The mapObject to be added to the specified {@code MapObjectLayer}. * @return The added map object. */ public IMapObject add(IMapObjectLayer layer, IMapObject mapObject) { @@ -270,8 +269,7 @@ public IMapObject add(IMapObjectLayer layer, IMapObject mapObject) { /** * It is crucial to call this before using the generated map of this instance.
*

- * This will call the {@code finish} method on the map instance and make sure that the generated map is available over - * the resources API. + * This will call the {@code finish} method on the map instance and make sure that the generated map is available over the resources API. *

* * @see TmxMap#finish(URL) diff --git a/litiengine/src/main/java/de/gurkenlabs/litiengine/resources/NamedResource.java b/litiengine/src/main/java/de/gurkenlabs/litiengine/resources/NamedResource.java index 8c1061b87..d60f4da87 100644 --- a/litiengine/src/main/java/de/gurkenlabs/litiengine/resources/NamedResource.java +++ b/litiengine/src/main/java/de/gurkenlabs/litiengine/resources/NamedResource.java @@ -3,16 +3,30 @@ import jakarta.xml.bind.annotation.XmlAttribute; import jakarta.xml.bind.annotation.XmlTransient; +/** + * An abstract class representing a named resource. This class implements the Resource interface and provides methods to get and set the resource + * name. + */ public abstract class NamedResource implements Resource { @XmlAttribute private String name; + /** + * Gets the name of the resource. + * + * @return The name of the resource. + */ @XmlTransient @Override public String getName() { return this.name; } + /** + * Sets the name of the resource. + * + * @param n The new name of the resource. + */ @Override public void setName(final String n) { this.name = n; diff --git a/litiengine/src/main/java/de/gurkenlabs/litiengine/resources/Resource.java b/litiengine/src/main/java/de/gurkenlabs/litiengine/resources/Resource.java index a604fde95..d1324bce4 100644 --- a/litiengine/src/main/java/de/gurkenlabs/litiengine/resources/Resource.java +++ b/litiengine/src/main/java/de/gurkenlabs/litiengine/resources/Resource.java @@ -2,17 +2,31 @@ import de.gurkenlabs.litiengine.util.AlphanumComparator; +/** + * Represents a resource that can be compared to other resources. This interface extends the Comparable interface for Resource objects. + */ public interface Resource extends Comparable { /** - * Gets the name. + * Gets the name of the resource. * - * @return the name + * @return The name of the resource. */ String getName(); + /** + * Sets the name of the resource. + * + * @param name The new name of the resource. + */ void setName(String name); + /** + * Compares this resource with the specified resource for order. + * + * @param obj The resource to be compared. + * @return A negative integer, zero, or a positive integer as this resource is less than, equal to, or greater than the specified resource. + */ @Override default int compareTo(Resource obj) { return AlphanumComparator.compareTo(this.getName(), obj.getName()); diff --git a/litiengine/src/main/java/de/gurkenlabs/litiengine/resources/ResourceBundle.java b/litiengine/src/main/java/de/gurkenlabs/litiengine/resources/ResourceBundle.java index ddf1120b5..5332833ca 100644 --- a/litiengine/src/main/java/de/gurkenlabs/litiengine/resources/ResourceBundle.java +++ b/litiengine/src/main/java/de/gurkenlabs/litiengine/resources/ResourceBundle.java @@ -34,6 +34,10 @@ import java.util.zip.GZIPOutputStream; import java.util.zip.ZipException; +/** + * Represents a resource bundle that can be serialized. This class is used to manage various game resources such as maps, sprite sheets, tilesets, + * emitters, blueprints, and sounds. + */ @XmlRootElement(name = "litidata") public class ResourceBundle implements Serializable { private static final Logger log = Logger.getLogger(ResourceBundle.class.getName()); @@ -69,6 +73,9 @@ public class ResourceBundle implements Serializable { @XmlElement(name = "sound") private final List sounds; + /** + * Constructs a new ResourceBundle instance. Initializes the lists for sprite sheets, maps, tilesets, emitters, blueprints, and sounds. + */ public ResourceBundle() { this.spriteSheets = new ArrayList<>(); this.maps = new ArrayList<>(); @@ -78,10 +85,22 @@ public ResourceBundle() { this.sounds = new ArrayList<>(); } + /** + * Loads a ResourceBundle from a file path. + * + * @param file The file path to load the ResourceBundle from. + * @return The loaded ResourceBundle, or null if loading fails. + */ public static ResourceBundle load(String file) { return load(Resources.getLocation(file)); } + /** + * Loads a ResourceBundle from a URL. + * + * @param file The URL to load the ResourceBundle from. + * @return The loaded ResourceBundle, or null if loading fails. + */ public static ResourceBundle load(final URL file) { try { ResourceBundle gameFile = getResourceBundle(file); @@ -110,36 +129,73 @@ public static ResourceBundle load(final URL file) { return null; } + /** + * Gets the list of maps in this resource bundle. + * + * @return The list of maps. + */ @XmlTransient public List getMaps() { return this.maps; } + /** + * Gets the list of sprite sheets in this resource bundle. + * + * @return The list of sprite sheets. + */ @XmlTransient public List getSpriteSheets() { return this.spriteSheets; } + /** + * Gets the list of tilesets in this resource bundle. + * + * @return The list of tilesets. + */ @XmlTransient public List getTilesets() { return this.tilesets; } + /** + * Gets the list of emitters in this resource bundle. + * + * @return The list of emitters. + */ @XmlTransient public List getEmitters() { return this.emitters; } + /** + * Gets the list of blueprints in this resource bundle. + * + * @return The list of blueprints. + */ @XmlTransient public List getBluePrints() { return this.blueprints; } + /** + * Gets the list of sounds in this resource bundle. + * + * @return The list of sounds. + */ @XmlTransient public List getSounds() { return this.sounds; } + /** + * Saves the ResourceBundle to a file. + * + * @param fileName The name of the file to save the ResourceBundle to. + * @param compress Whether to compress the file or not. + * @return The path of the saved file as a string. + */ public String save(final String fileName, final boolean compress) { String fileNameWithExtension = fileName; if (!fileNameWithExtension.endsWith("." + FILE_EXTENSION)) { @@ -192,6 +248,12 @@ public String save(final String fileName, final boolean compress) { return newFile.toString(); } + /** + * Prepares the ResourceBundle for marshalling. This method ensures that the lists of sprite sheets and tilesets contain only distinct elements. It + * also sets the version of the ResourceBundle if it is not already set. + * + * @param m The Marshaller instance used for marshalling. + */ void beforeMarshal(Marshaller m) { List distinctList = new ArrayList<>(); for (SpritesheetResource sprite : this.getSpriteSheets()) { @@ -220,6 +282,15 @@ void beforeMarshal(Marshaller m) { } } + /** + * Retrieves a ResourceBundle from a specified URL. This method attempts to load the ResourceBundle from a compressed GZIP stream first. If that + * fails, it falls back to loading from plain XML. + * + * @param file The URL of the resource bundle file. + * @return The loaded ResourceBundle. + * @throws JAXBException If an error occurs during the unmarshalling process. + * @throws IOException If an I/O error occurs. + */ private static ResourceBundle getResourceBundle(URL file) throws JAXBException, IOException { final JAXBContext jaxbContext = XmlUtilities.getContext(ResourceBundle.class); final Unmarshaller um = jaxbContext.createUnmarshaller(); diff --git a/litiengine/src/main/java/de/gurkenlabs/litiengine/resources/ResourceLoadException.java b/litiengine/src/main/java/de/gurkenlabs/litiengine/resources/ResourceLoadException.java index 9f0b64613..0cdd0f21d 100644 --- a/litiengine/src/main/java/de/gurkenlabs/litiengine/resources/ResourceLoadException.java +++ b/litiengine/src/main/java/de/gurkenlabs/litiengine/resources/ResourceLoadException.java @@ -1,18 +1,43 @@ package de.gurkenlabs.litiengine.resources; +import java.io.Serial; + +/** + * Exception thrown when a resource fails to load. + */ public class ResourceLoadException extends RuntimeException { - private static final long serialVersionUID = 2690585643366673974L; + @Serial private static final long serialVersionUID = 2690585643366673974L; - public ResourceLoadException() {} + /** + * Constructs a new ResourceLoadException with {@code null} as its detail message. + */ + public ResourceLoadException() { + } + /** + * Constructs a new ResourceLoadException with the specified detail message. + * + * @param message The detail message. + */ public ResourceLoadException(String message) { super(message); } + /** + * Constructs a new ResourceLoadException with the specified cause. + * + * @param cause The cause of the exception. + */ public ResourceLoadException(Throwable cause) { super(cause); } + /** + * Constructs a new ResourceLoadException with the specified detail message and cause. + * + * @param message The detail message. + * @param cause The cause of the exception. + */ public ResourceLoadException(String message, Throwable cause) { super(message, cause); } diff --git a/litiengine/src/main/java/de/gurkenlabs/litiengine/resources/Resources.java b/litiengine/src/main/java/de/gurkenlabs/litiengine/resources/Resources.java index ef435c533..b2a633774 100644 --- a/litiengine/src/main/java/de/gurkenlabs/litiengine/resources/Resources.java +++ b/litiengine/src/main/java/de/gurkenlabs/litiengine/resources/Resources.java @@ -1,5 +1,13 @@ package de.gurkenlabs.litiengine.resources; +import de.gurkenlabs.litiengine.environment.tilemap.IMap; +import de.gurkenlabs.litiengine.environment.tilemap.xml.Blueprint; +import de.gurkenlabs.litiengine.environment.tilemap.xml.Tileset; +import de.gurkenlabs.litiengine.graphics.Spritesheet; +import de.gurkenlabs.litiengine.graphics.emitters.xml.EmitterData; +import de.gurkenlabs.litiengine.graphics.emitters.xml.EmitterLoader; +import de.gurkenlabs.litiengine.sound.Sound; +import de.gurkenlabs.litiengine.util.TimeUtilities; import java.awt.Font; import java.awt.image.BufferedImage; import java.io.BufferedInputStream; @@ -17,23 +25,14 @@ import java.util.logging.Level; import java.util.logging.Logger; -import de.gurkenlabs.litiengine.environment.tilemap.IMap; -import de.gurkenlabs.litiengine.environment.tilemap.xml.Blueprint; -import de.gurkenlabs.litiengine.environment.tilemap.xml.Tileset; -import de.gurkenlabs.litiengine.graphics.Spritesheet; -import de.gurkenlabs.litiengine.graphics.emitters.xml.EmitterData; -import de.gurkenlabs.litiengine.graphics.emitters.xml.EmitterLoader; -import de.gurkenlabs.litiengine.sound.Sound; -import de.gurkenlabs.litiengine.util.TimeUtilities; - /** - * This class is the engines entry point for accessing any kind of resources. A resource is any non-executable data that - * is deployed with your game. The {@code Resources} class provides access to types of {@code ResourcesContainers} and - * is used by different (loading) mechanisms to make resources available during runtime. + * This class is the engines entry point for accessing any kind of resources. A resource is any non-executable data that is deployed with your game. + * The {@code Resources} class provides access to types of {@code ResourcesContainers} and is used by different (loading) mechanisms to make resources + * available during runtime. *

* The LITIENGINE supports a variety of different resource types, including: *

- * + * *
    *
  • images
    • *
  • fonts
    • @@ -42,7 +41,7 @@ *
  • spritesheets
    • *
  • sounds
    • *
- * + * * @see ResourcesContainer */ public final class Resources { @@ -62,9 +61,8 @@ private Resources() { /** * Gets the container that manages {@code Font} resources. - * + * * @return The Font resource container. - * * @see Font */ public static Fonts fonts() { @@ -73,9 +71,8 @@ public static Fonts fonts() { /** * Gets the container that manages {@code Sound} resources. - * + * * @return The Sound resource container. - * * @see Sound */ public static Sounds sounds() { @@ -84,9 +81,8 @@ public static Sounds sounds() { /** * Gets the container that manages {@code IMap} resources. - * + * * @return The IMap resource container. - * * @see IMap */ public static Maps maps() { @@ -94,12 +90,10 @@ public static Maps maps() { } /** - * Gets the container that manages {@code Tileset} resources.
- * This implementation uses raw {@code Tileset}s, to avoid problems with {@code Tileset} methods that aren't in the - * {@code ITileset} interface. - * + * Gets the container that manages {@code Tileset} resources.
This implementation uses raw {@code Tileset}s, to avoid problems with + * {@code Tileset} methods that aren't in the {@code ITileset} interface. + * * @return The Tileset resource container. - * * @see Tileset */ public static Tilesets tilesets() { @@ -107,9 +101,8 @@ public static Tilesets tilesets() { } /** - * Gets a container that manages {@code String} resources.
- * This instance can be used to access localizable string from a ".properties" file. - * + * Gets a container that manages {@code String} resources.
This instance can be used to access localizable string from a ".properties" file. + * * @return The String resource container. */ public static Strings strings() { @@ -118,9 +111,8 @@ public static Strings strings() { /** * Gets the container that manages {@code BufferedImage} resources. - * + * * @return The BufferedImage resource container. - * * @see BufferedImage */ public static Images images() { @@ -129,9 +121,8 @@ public static Images images() { /** * Gets the container that manages {@code Spritesheet} resources. - * + * * @return The Spritesheet resource container. - * * @see Spritesheet */ public static Spritesheets spritesheets() { @@ -140,9 +131,8 @@ public static Spritesheets spritesheets() { /** * Gets the container that manages {@code Blueprint} resources. - * + * * @return The Blueprint resource container. - * * @see Blueprint */ public static Blueprints blueprints() { @@ -150,22 +140,20 @@ public static Blueprints blueprints() { } /** - * Load {@code Spritesheets}, {@code Tilesets} and {@code Maps} from a game resource file created with the utiLITI - * editor. After loading, these resources can be accessed via this API (e.g. {@code Resources.maps().get("mapname")}. - * - * @param gameResourceFile - * The file name of the game resource file + * Load {@code Spritesheets}, {@code Tilesets} and {@code Maps} from a game resource file created with the utiLITI editor. After loading, these + * resources can be accessed via this API (e.g. {@code Resources.maps().get("mapname")}. + * + * @param gameResourceFile The file name of the game resource file */ public static void load(final String gameResourceFile) { load(getLocation(gameResourceFile)); } /** - * Load {@code Spritesheets}, {@code Tilesets} and {@code Maps} from a game resource file created with the utiLITI - * editor. After loading, these resources can be accessed via this API (e.g. {@code Resources.maps().get("mapname")}. - * - * @param gameResourceFile - * The URL to the game resource file + * Load {@code Spritesheets}, {@code Tilesets} and {@code Maps} from a game resource file created with the utiLITI editor. After loading, these + * resources can be accessed via this API (e.g. {@code Resources.maps().get("mapname")}. + * + * @param gameResourceFile The URL to the game resource file */ public static void load(final URL gameResourceFile) { final long loadStart = System.nanoTime(); @@ -234,9 +222,8 @@ public static void load(final URL gameResourceFile) { /** * Gets the specified file as InputStream from either a resource folder or the file system. - * - * @param file - * The path to the file. + * + * @param file The path to the file. * @return The contents of the specified file as {@code InputStream}. * @see Resources */ @@ -246,9 +233,8 @@ public static InputStream get(String file) { /** * Gets the specified file as InputStream from either a resource folder or the file system. - * - * @param file - * The path to the file. + * + * @param file The path to the file. * @return The contents of the specified file as {@code InputStream}. * @see Resources */ @@ -262,11 +248,10 @@ public static InputStream get(URL file) { } /** - * Reads the specified file as String from either a resource folder or the file system.
- * Since no {@code Charset} is specified with this overload, the implementation uses UTF-8 by default. - * - * @param file - * The path to the file. + * Reads the specified file as String from either a resource folder or the file system.
Since no {@code Charset} is specified with this + * overload, the implementation uses UTF-8 by default. + * + * @param file The path to the file. * @return The contents of the specified file as {@code String} */ public static String read(String file) { @@ -275,11 +260,9 @@ public static String read(String file) { /** * Reads the specified file as String from either a resource folder or the file system.
- * - * @param file - * The path to the file. - * @param charset - * The charset that is used to read the String from the file. + * + * @param file The path to the file. + * @param charset The charset that is used to read the String from the file. * @return The contents of the specified file as {@code String} */ public static String read(String file, Charset charset) { @@ -292,11 +275,10 @@ public static String read(String file, Charset charset) { } /** - * Reads the specified file as String from either a resource folder or the file system.
- * Since no {@code Charset} is specified with this overload, the implementation uses UTF-8 by default. - * - * @param file - * The path to the file. + * Reads the specified file as String from either a resource folder or the file system.
Since no {@code Charset} is specified with this + * overload, the implementation uses UTF-8 by default. + * + * @param file The path to the file. * @return The contents of the specified file as {@code String} */ public static String read(URL file) { @@ -305,15 +287,13 @@ public static String read(URL file) { /** * Reads the specified file as String from either a resource folder or the file system.
- * - * @param file - * The path to the file. - * @param charset - * The charset that is used to read the String from the file. + * + * @param file The path to the file. + * @param charset The charset that is used to read the String from the file. * @return The contents of the specified file as {@code String} */ public static String read(URL file, Charset charset) { - try (Scanner scanner = new Scanner(file.openStream(), charset.toString())) { + try (Scanner scanner = new Scanner(file.openStream(), charset)) { scanner.useDelimiter("\\A"); return scanner.hasNext() ? scanner.next() : null; } catch (IOException e) { @@ -334,22 +314,31 @@ public static void clearAll() { spritesheets().clear(); } + /** + * Gets the location of the specified resource. This method attempts to find the resource using the system class loader first. If the resource is + * not found, it tries to locate it as a file in the file system. + * + * @param name The name of the resource. + * @return The URL of the resource, or null if the resource could not be found. + */ public static URL getLocation(String name) { URL fromClass = ClassLoader.getSystemResource(name); if (fromClass != null) { return fromClass; } try { - return new URL(name); + return (new File(name)).toURI().toURL(); } catch (MalformedURLException e) { - try { - return (new File(name)).toURI().toURL(); - } catch (MalformedURLException e1) { - return null; - } + return null; } } + /** + * Retrieves an InputStream for the specified URL. This method attempts to open a stream to the resource located at the given URL. + * + * @param file The URL of the resource to be accessed. + * @return An InputStream to the resource, or null if an I/O error occurs. + */ private static InputStream getResource(final URL file) { try { return file.openStream(); diff --git a/litiengine/src/main/java/de/gurkenlabs/litiengine/resources/ResourcesContainer.java b/litiengine/src/main/java/de/gurkenlabs/litiengine/resources/ResourcesContainer.java index d014e47ef..5d98ee49b 100644 --- a/litiengine/src/main/java/de/gurkenlabs/litiengine/resources/ResourcesContainer.java +++ b/litiengine/src/main/java/de/gurkenlabs/litiengine/resources/ResourcesContainer.java @@ -17,8 +17,8 @@ import java.util.function.Supplier; /** - * An abstract implementation for all classes that provide a certain type of resources. Basically, - * it's an in-memory cache of the resources and provides access to manage the resources. + * An abstract implementation for all classes that provide a certain type of resources. Basically, it's an in-memory cache of the resources and + * provides access to manage the resources. * * @param The type of the resource that is contained by this instance. * @see ResourcesContainerListener @@ -44,11 +44,10 @@ public void terminated() { } /** - * Add a new container listener to this instance in order to observe resource life cycles. The - * listener will get notified whenever a resource was added to or removed from this container. + * Add a new container listener to this instance in order to observe resource life cycles. The listener will get notified whenever a resource was + * added to or removed from this container. * - * @param listener The container listener instance that will receive call backs from this - * container. + * @param listener The container listener instance that will receive call backs from this container. * @see #removeContainerListener(ResourcesContainerListener) */ public void addContainerListener(ResourcesContainerListener listener) { @@ -86,8 +85,8 @@ public void removeClearedListener(ResourcesContainerClearedListener listener) { } /** - * Add the specified resource to this container.
The added element can later be retrieved from - * this container by calling {@code get(resourceName)}. + * Add the specified resource to this container.
The added element can later be retrieved from this container by calling + * {@code get(resourceName)}. *

* Use this method to make a resource accessible over this container during runtime. *

@@ -108,6 +107,13 @@ public void add(String resourceName, T resource) { } } + /** + * Adds the specified resource to this container using the given URL as the resource name. The added element can later be retrieved from this + * container by calling {@code get(resourceName)}. + * + * @param resourceName The URL of the resource to be added. + * @param resource The resource instance to be added. + */ public void add(URL resourceName, T resource) { this.add(resourceName.toString(), resource); } @@ -137,6 +143,12 @@ public boolean contains(String resourceName) { return this.resources.containsKey(this.getIdentifier(resourceName)); } + /** + * Checks if this instance contains a resource with the specified URL. + * + * @param resourceName The URL of the resource. + * @return True if this container contains a resource with the specified URL; otherwise false. + */ public boolean contains(URL resourceName) { return this.contains(resourceName.toString()); } @@ -180,8 +192,7 @@ public Collection get(Predicate pred) { * This is the most common (and preferred) way to fetch resources from a container. *

*

- * If not previously loaded, this method attempts to load the resource on the fly otherwise it - * will be retrieved from the cache. + * If not previously loaded, this method attempts to load the resource on the fly otherwise it will be retrieved from the cache. *

* * @param resourceName The resource's name. @@ -191,6 +202,15 @@ public T get(String resourceName) { return this.get(this.getIdentifier(resourceName), false); } + /** + * Gets the resource with the specified URL. + *

+ * If not previously loaded, this method attempts to load the resource on the fly; otherwise, it will be retrieved from the cache. + *

+ * + * @param resourceName The URL of the resource. + * @return The resource with the specified URL or null if not found. + */ public T get(URL resourceName) { return this.get(resourceName, false); } @@ -198,13 +218,12 @@ public T get(URL resourceName) { /** * Gets the resource with the specified name.
*

- * If no such resource is currently present on the container, it will be loaded with the specified - * {@code loadCallback} and added to this container. + * If no such resource is currently present on the container, it will be loaded with the specified {@code loadCallback} and added to this + * container. *

* * @param resourceName The resource's name. - * @param loadCallback The callback that is used to load the resource on-demand if it's not - * present on this container. + * @param loadCallback The callback that is used to load the resource on-demand if it's not present on this container. * @return T The resource with the specified name. */ public T get(String resourceName, Supplier loadCallback) { @@ -222,6 +241,17 @@ public T get(String resourceName, Supplier loadCallback) { } + /** + * Gets the resource with the specified URL. + *

+ * If no such resource is currently present in the container, it will be loaded with the specified {@code loadCallback} and added to this + * container. + *

+ * + * @param resourceName The URL of the resource. + * @param loadCallback The callback that is used to load the resource on-demand if it's not present in this container. + * @return The resource with the specified URL. + */ public T get(URL resourceName, Supplier loadCallback) { return this.get(resourceName.toString(), loadCallback); } @@ -229,13 +259,11 @@ public T get(URL resourceName, Supplier loadCallback) { /** * Gets the resource with the specified name. *

- * If not previously loaded, this method attempts to load the resource on the fly otherwise it - * will be retrieved from the cache. + * If not previously loaded, this method attempts to load the resource on the fly otherwise it will be retrieved from the cache. *

* * @param resourceName The name of the game resource. - * @param forceLoad If set to true, cached resource (if existing) will be discarded and the - * resource will be freshly loaded. + * @param forceLoad If set to true, cached resource (if existing) will be discarded and the resource will be freshly loaded. * @return The game resource or null if not found. */ public T get(String resourceName, boolean forceLoad) { @@ -257,31 +285,37 @@ public T get(String resourceName, boolean forceLoad) { } } + /** + * Gets the resource with the specified URL. + *

+ * If not previously loaded, this method attempts to load the resource on the fly; otherwise, it will be retrieved from the cache. + *

+ * + * @param resourceName The URL of the resource. + * @param forceLoad If set to true, cached resource (if existing) will be discarded and the resource will be freshly loaded. + * @return The resource with the specified URL or null if not found. + */ public T get(URL resourceName, boolean forceLoad) { return this.get(resourceName.toString(), forceLoad); } /** - * Eventually gets the resource with the specified location. The resource is loaded asynchronously - * and can be retrieved from the returned {@code Future} object returned by this method once - * loaded. + * Eventually gets the resource with the specified location. The resource is loaded asynchronously and can be retrieved from the returned + * {@code Future} object returned by this method once loaded. * * @param location The location of the resource - * @return A {@code Future} object that can be used to retrieve the resource once it is finished - * loading + * @return A {@code Future} object that can be used to retrieve the resource once it is finished loading */ public Future getAsync(URL location) { return ASYNC_POOL.submit(() -> this.get(location)); } /** - * Eventually gets the resource with the specified location. The resource is loaded asynchronously - * and can be retrieved from the returned {@code Future} object returned by this method once - * loaded. + * Eventually gets the resource with the specified location. The resource is loaded asynchronously and can be retrieved from the returned + * {@code Future} object returned by this method once loaded. * * @param name The name or location of the resource - * @return A {@code Future} object that can be used to retrieve the resource once it is finished - * loading + * @return A {@code Future} object that can be used to retrieve the resource once it is finished loading */ public Future getAsync(String name) { return this.getAsync(Resources.getLocation(this.getIdentifier(name))); @@ -315,6 +349,12 @@ public T remove(String resourceName) { } + /** + * Removes the resource with the specified URL from this container. + * + * @param resourceName The URL of the resource that should be removed. + * @return The removed resource. + */ public T remove(URL resourceName) { return this.remove(resourceName.toString()); } @@ -322,10 +362,8 @@ public T remove(URL resourceName) { /** * Tries to get a resource with the specified name from this container. *

- * This method should be used, if it's not clear whether the resource is present on this - * container.
It is basically a combination of {@code get(String)} and - * {@code contains(String)} and allows to check whether a resource is present while also fetching - * it from the container. + * This method should be used, if it's not clear whether the resource is present on this container.
It is basically a combination of + * {@code get(String)} and {@code contains(String)} and allows to check whether a resource is present while also fetching it from the container. *

* * @param resourceName The name of the resource. @@ -342,15 +380,34 @@ public Optional tryGet(String resourceName) { return Optional.empty(); } + /** + * Tries to get a resource with the specified URL from this container. + *

+ * This method should be used if it's not clear whether the resource is present in this container. It is basically a combination of {@code get(URL)} + * and {@code contains(URL)} and allows checking whether a resource is present while also fetching it from the container. + *

+ * + * @param resourceName The URL of the resource. + * @return An Optional instance that holds the resource instance, if present in this container. + */ public Optional tryGet(URL resourceName) { return this.tryGet(resourceName.getPath()); } + /** + * Loads the resource with the specified URL. + *

+ * This method must be implemented by subclasses to define how a resource is loaded from the given URL. + *

+ * + * @param resourceName The URL of the resource to be loaded. + * @return The loaded resource. + * @throws Exception If an error occurs while loading the resource. + */ protected abstract T load(URL resourceName) throws Exception; /** - * Gets an alias for the specified resourceName. Note that the process of providing an alias is up - * to the ResourceContainer implementation. + * Gets an alias for the specified resourceName. Note that the process of providing an alias is up to the ResourceContainer implementation. * * @param resourceName The original name of the resource. * @param resource The resource. @@ -360,10 +417,26 @@ protected String getAlias(String resourceName, T resource) { return null; } + /** + * Gets the map of resources contained in this container. + * + * @return A map where the keys are resource names and the values are the resources. + */ protected Map getResources() { return this.resources; } + /** + * Loads the resource with the specified identifier. + *

+ * This method attempts to load the resource using the provided identifier. If the resource is successfully loaded, it notifies all registered + * listeners and updates the alias map if an alias is provided. + *

+ * + * @param identifier The identifier of the resource to be loaded. + * @return The loaded resource. + * @throws ResourceLoadException If an error occurs while loading the resource. + */ private T loadResource(String identifier) { T newResource; try { @@ -384,6 +457,15 @@ private T loadResource(String identifier) { return newResource; } + /** + * Gets the identifier for the specified resource name. + *

+ * This method checks if there is an alias for the given resource name and returns it. If no alias is found, it returns the original resource name. + *

+ * + * @param resourceName The name of the resource. + * @return The identifier for the resource, which may be an alias or the original resource name. + */ private String getIdentifier(String resourceName) { return this.aliases.getOrDefault(resourceName, resourceName); } diff --git a/litiengine/src/main/java/de/gurkenlabs/litiengine/resources/ResourcesContainerListener.java b/litiengine/src/main/java/de/gurkenlabs/litiengine/resources/ResourcesContainerListener.java index 41c44913b..317dda2be 100644 --- a/litiengine/src/main/java/de/gurkenlabs/litiengine/resources/ResourcesContainerListener.java +++ b/litiengine/src/main/java/de/gurkenlabs/litiengine/resources/ResourcesContainerListener.java @@ -3,40 +3,42 @@ /** * This listener provides callbacks to observe {@code ResourcesContainer} instances. * - * @param - * The type of the resource that is managed by the container. - * + * @param The type of the resource that is managed by the container. * @see ResourcesContainer * @see Images * @see Fonts * @see Maps * @see Sounds * @see Spritesheets - * */ public interface ResourcesContainerListener extends ResourcesContainerClearedListener { /** * This method gets called after the {@code ResourcesContainer.add} method was executed. - * - * @param resourceName - * The name by which the added resource is identified. - * @param resource - * The added resource. + * + * @param resourceName The name by which the added resource is identified. + * @param resource The added resource. * @see ResourcesContainer#add(String, Object) */ - default void added(String resourceName, T resource) {} + default void added(String resourceName, T resource) { + } /** * This method gets called after the {@code ResourcesContainer.remove} method was executed. - * - * @param resourceName - * The name by which the removed resource was identified. - * @param resource - * The removed resource. + * + * @param resourceName The name by which the removed resource was identified. + * @param resource The removed resource. * @see ResourcesContainer#remove(String) */ - default void removed(String resourceName, T resource) {} + default void removed(String resourceName, T resource) { + } - default void cleared() {} + /** + * This method gets called after the {@code ResourcesContainer.clear} method was executed. It notifies that all resources have been removed from the + * container. + * + * @see ResourcesContainer#clear() + */ + default void cleared() { + } } diff --git a/litiengine/src/main/java/de/gurkenlabs/litiengine/resources/SoundFormat.java b/litiengine/src/main/java/de/gurkenlabs/litiengine/resources/SoundFormat.java index 5d4ba760f..0d04113d5 100644 --- a/litiengine/src/main/java/de/gurkenlabs/litiengine/resources/SoundFormat.java +++ b/litiengine/src/main/java/de/gurkenlabs/litiengine/resources/SoundFormat.java @@ -43,13 +43,18 @@ public static boolean isSupported(String fileName) { return DataFormat.isSupported(fileName, values(), UNSUPPORTED); } + /** + * Gets all the file extensions supported by the engine. + * + * @return An array of strings representing all supported file extensions. + */ public static String[] getAllExtensions() { return DataFormat.getAllExtensions(values(), UNSUPPORTED); } /** - * Converts this format instance to a file format string that can be used as an extension (e.g. - * .ogg).
It adds a leading '.' to the lower-case string representation of this instance. + * Converts this format instance to a file format string that can be used as an extension (e.g. .ogg).
It adds a leading '.' to the lower-case + * string representation of this instance. * * @return The file extension string for this instance. */ diff --git a/litiengine/src/main/java/de/gurkenlabs/litiengine/resources/SoundResource.java b/litiengine/src/main/java/de/gurkenlabs/litiengine/resources/SoundResource.java index 6540c4fee..a114ac4b2 100644 --- a/litiengine/src/main/java/de/gurkenlabs/litiengine/resources/SoundResource.java +++ b/litiengine/src/main/java/de/gurkenlabs/litiengine/resources/SoundResource.java @@ -1,16 +1,20 @@ package de.gurkenlabs.litiengine.resources; -import java.io.IOException; -import java.io.InputStream; - -import javax.sound.sampled.UnsupportedAudioFileException; +import de.gurkenlabs.litiengine.sound.Sound; +import de.gurkenlabs.litiengine.util.io.Codec; import jakarta.xml.bind.annotation.XmlElement; import jakarta.xml.bind.annotation.XmlRootElement; import jakarta.xml.bind.annotation.XmlTransient; +import java.io.IOException; +import java.io.InputStream; +import javax.sound.sampled.UnsupportedAudioFileException; -import de.gurkenlabs.litiengine.sound.Sound; -import de.gurkenlabs.litiengine.util.io.Codec; - +/** + * Represents a sound resource that extends the NamedResource class. + *

+ * This class is used to manage sound resources, including their data and format. + *

+ */ @XmlRootElement(name = "sound") public class SoundResource extends NamedResource { @XmlElement(name = "data") @@ -19,34 +23,95 @@ public class SoundResource extends NamedResource { @XmlElement(name = "format") private SoundFormat format = SoundFormat.UNSUPPORTED; + /** + * Default constructor for SoundResource. + *

+ * This constructor doesn't do anything and is intended for XML serialization purposes. + *

+ */ public SoundResource() { // keep for xml serialization } + /** + * Constructs a new SoundResource with the specified sound and format. + *

+ * This constructor initializes the SoundResource with the provided Sound object and SoundFormat. It sets the name of the resource to the name of + * the sound and encodes the raw data of the sound. + *

+ * + * @param sound The Sound object to be used for this resource. + * @param format The format of the sound. + */ public SoundResource(Sound sound, SoundFormat format) { this.setName(sound.getName()); this.data = Codec.encode(sound.getRawData()); this.format = format; } + /** + * Constructs a new SoundResource with the specified input stream, name, and format. + *

+ * This constructor initializes the SoundResource by creating a new Sound object from the provided input stream and name, and sets the format of the + * sound. + *

+ * + * @param data The input stream containing the sound data. + * @param name The name of the sound. + * @param format The format of the sound. + * @throws IOException If an I/O error occurs while reading the sound data. + * @throws UnsupportedAudioFileException If the audio file format is not supported. + */ public SoundResource(InputStream data, String name, SoundFormat format) throws IOException, UnsupportedAudioFileException { this(new Sound(data, name), format); } + /** + * Gets the encoded sound data. + *

+ * This method returns the encoded sound data as a string. + *

+ * + * @return The encoded sound data. + */ @XmlTransient public String getData() { return this.data; } + /** + * Gets the format of the sound. + *

+ * This method returns the format of the sound. + *

+ * + * @return The format of the sound. + */ @XmlTransient public SoundFormat getFormat() { return this.format; } + /** + * Sets the encoded sound data. + *

+ * This method sets the encoded sound data. + *

+ * + * @param data The encoded sound data to set. + */ public void setData(String data) { this.data = data; } + /** + * Sets the format of the sound. + *

+ * This method sets the format of the sound. + *

+ * + * @param format The format of the sound to set. + */ public void setFormat(SoundFormat format) { this.format = format; } diff --git a/litiengine/src/main/java/de/gurkenlabs/litiengine/resources/Sounds.java b/litiengine/src/main/java/de/gurkenlabs/litiengine/resources/Sounds.java index 781cc1bbd..09acc1368 100644 --- a/litiengine/src/main/java/de/gurkenlabs/litiengine/resources/Sounds.java +++ b/litiengine/src/main/java/de/gurkenlabs/litiengine/resources/Sounds.java @@ -1,31 +1,33 @@ package de.gurkenlabs.litiengine.resources; +import de.gurkenlabs.litiengine.sound.Sound; +import de.gurkenlabs.litiengine.util.io.Codec; +import de.gurkenlabs.litiengine.util.io.FileUtilities; import java.io.ByteArrayInputStream; import java.io.IOException; import java.io.InputStream; import java.net.URL; import java.util.logging.Level; import java.util.logging.Logger; - import javax.sound.sampled.UnsupportedAudioFileException; -import de.gurkenlabs.litiengine.sound.Sound; -import de.gurkenlabs.litiengine.util.io.Codec; -import de.gurkenlabs.litiengine.util.io.FileUtilities; - +/** + * Represents a container for managing sound resources. + *

+ * This class extends the {@code ResourcesContainer} class to provide specific functionality for handling {@code Sound} objects. + *

+ */ public final class Sounds extends ResourcesContainer { private static final Logger log = Logger.getLogger(Sounds.class.getName()); - Sounds() {} + Sounds() { + } /** * Loads a sound from the specified XML resource. - * - * @param resource - * The XML resource that contains the sound as Base64 string. - * + * + * @param resource The XML resource that contains the sound as Base64 string. * @return The {@code Sound} instance loaded from the specified resource. - * * @see Codec#decode(String) */ public Sound load(final SoundResource resource) { @@ -45,9 +47,8 @@ public Sound load(final SoundResource resource) { /** * Loads the sound from the specified path and returns it. - * - * @param resourceName - * The path of the file to be loaded.(Can be relative or absolute) + * + * @param resourceName The path of the file to be loaded.(Can be relative or absolute) * @return The loaded Sound from the specified path. */ @Override diff --git a/litiengine/src/main/java/de/gurkenlabs/litiengine/resources/SpritesheetResource.java b/litiengine/src/main/java/de/gurkenlabs/litiengine/resources/SpritesheetResource.java index 0b1275bf8..a816bf375 100644 --- a/litiengine/src/main/java/de/gurkenlabs/litiengine/resources/SpritesheetResource.java +++ b/litiengine/src/main/java/de/gurkenlabs/litiengine/resources/SpritesheetResource.java @@ -1,18 +1,23 @@ package de.gurkenlabs.litiengine.resources; -import java.awt.image.BufferedImage; -import java.io.Serializable; - +import de.gurkenlabs.litiengine.graphics.Spritesheet; +import de.gurkenlabs.litiengine.util.ArrayUtilities; +import de.gurkenlabs.litiengine.util.io.Codec; import jakarta.xml.bind.Marshaller; import jakarta.xml.bind.annotation.XmlAttribute; import jakarta.xml.bind.annotation.XmlElement; import jakarta.xml.bind.annotation.XmlRootElement; import jakarta.xml.bind.annotation.XmlTransient; +import java.awt.image.BufferedImage; +import java.io.Serializable; -import de.gurkenlabs.litiengine.graphics.Spritesheet; -import de.gurkenlabs.litiengine.util.ArrayUtilities; -import de.gurkenlabs.litiengine.util.io.Codec; - +/** + * Represents a resource for managing spritesheets. + *

+ * This class extends the {@code NamedResource} class and implements {@code Serializable} to provide specific functionality for handling spritesheet + * resources. + *

+ */ @XmlRootElement(name = "sprite") public class SpritesheetResource extends NamedResource implements Serializable { public static final String PLAIN_TEXT_FILE_EXTENSION = "info"; @@ -32,10 +37,24 @@ public class SpritesheetResource extends NamedResource implements Serializable { @XmlElement(required = false) private String keyframes; + /** + * Default constructor for SpritesheetResource. + *

+ * This constructor is kept for serialization purposes. + *

+ */ public SpritesheetResource() { // keep empty constructor for serialization } + /** + * Constructs a new SpritesheetResource from a Spritesheet object. + *

+ * This constructor initializes the SpritesheetResource with the specified sprite's width, height, name, image, image format, and keyframes. + *

+ * + * @param sprite The Spritesheet object to initialize the resource from. + */ public SpritesheetResource(final Spritesheet sprite) { this(sprite.getSpriteWidth(), sprite.getSpriteHeight(), sprite.getName()); this.setImage(Codec.encode(sprite.getImage(), sprite.getImageFormat())); @@ -43,38 +62,84 @@ public SpritesheetResource(final Spritesheet sprite) { this.setKeyframes(Resources.spritesheets().getCustomKeyFrameDurations(sprite)); } + /** + * Constructs a new SpritesheetResource from a BufferedImage. + *

+ * This constructor initializes the SpritesheetResource with the specified image, name, width, and height. + *

+ * + * @param image The BufferedImage to initialize the resource from. + * @param name The name of the spritesheet. + * @param width The width of the spritesheet. + * @param height The height of the spritesheet. + */ public SpritesheetResource(final BufferedImage image, String name, final int width, final int height) { this(width, height, name); this.setImage(Codec.encode(image)); this.setImageFormat(ImageFormat.PNG); } + /** + * Constructs a new SpritesheetResource with the specified width, height, and name. + *

+ * This private constructor is used internally to initialize the resource with the specified dimensions and name. + *

+ * + * @param width The width of the spritesheet. + * @param height The height of the spritesheet. + * @param name The name of the spritesheet. + */ private SpritesheetResource(int width, int height, String name) { this.setWidth(width); this.setHeight(height); this.setName(name); } + /** + * Gets the height of the spritesheet. + * + * @return The height of the spritesheet. + */ @XmlTransient public int getHeight() { return this.height; } + /** + * Gets the image data of the spritesheet. + * + * @return The image data of the spritesheet. + */ @XmlTransient public String getImage() { return this.image; } + /** + * Gets the width of the spritesheet. + * + * @return The width of the spritesheet. + */ @XmlTransient public int getWidth() { return this.width; } + /** + * Gets the image format of the spritesheet. + * + * @return The image format of the spritesheet. + */ @XmlTransient public ImageFormat getImageFormat() { return this.imageformat; } + /** + * Gets the keyframes of the spritesheet. + * + * @return An array of keyframes of the spritesheet. + */ @XmlTransient public int[] getKeyframes() { if (this.keyframes == null || this.keyframes.isEmpty()) { @@ -84,26 +149,59 @@ public int[] getKeyframes() { return ArrayUtilities.splitInt(this.keyframes); } + /** + * Sets the height of the spritesheet. + * + * @param h The height to set. + */ public void setHeight(final int h) { this.height = h; } + /** + * Sets the image data of the spritesheet. + * + * @param image The image data to set. + */ public void setImage(final String image) { this.image = image; } + /** + * Sets the width of the spritesheet. + * + * @param w The width to set. + */ public void setWidth(final int w) { this.width = w; } + /** + * Sets the image format of the spritesheet. + * + * @param f The image format to set. + */ public void setImageFormat(final ImageFormat f) { this.imageformat = f; } + /** + * Sets the keyframes of the spritesheet. + * + * @param keyframes An array of keyframes to set. + */ public void setKeyframes(int[] keyframes) { this.keyframes = ArrayUtilities.join(keyframes); } + /** + * Prepares the object for marshalling. + *

+ * This method is called before the object is marshalled to XML. It ensures that the keyframes field is set to null if it is empty. + *

+ * + * @param m The marshaller. + */ @SuppressWarnings("unused") private void beforeMarshal(Marshaller m) { if (this.keyframes != null && this.keyframes.isEmpty()) { diff --git a/litiengine/src/main/java/de/gurkenlabs/litiengine/resources/Spritesheets.java b/litiengine/src/main/java/de/gurkenlabs/litiengine/resources/Spritesheets.java index 2490017d3..fe354130b 100644 --- a/litiengine/src/main/java/de/gurkenlabs/litiengine/resources/Spritesheets.java +++ b/litiengine/src/main/java/de/gurkenlabs/litiengine/resources/Spritesheets.java @@ -26,6 +26,13 @@ import java.util.logging.Level; import java.util.logging.Logger; +/** + * Manages the loading, storing, and retrieval of spritesheets. + *

+ * This class provides methods to load spritesheets from various sources, manage custom keyframe durations, and handle listeners for resource + * container clearing events. + *

+ */ public final class Spritesheets { private final Map customKeyFrameDurations = new ConcurrentHashMap<>(); private final Map loadedSpritesheets = new ConcurrentHashMap<>(); @@ -36,23 +43,48 @@ public final class Spritesheets { Spritesheets() { } + /** + * Adds a spritesheet to the collection of loaded spritesheets. + * + * @param name The name of the spritesheet. + * @param spritesheet The spritesheet to add. + */ public void add(String name, Spritesheet spritesheet) { this.loadedSpritesheets.put(name, spritesheet); } + /** + * Adds a listener for resource container clearing events. + * + * @param listener The listener to add. + */ public void addClearedListener(ResourcesContainerClearedListener listener) { this.listeners.add(listener); } + /** + * Removes a listener for resource container clearing events. + * + * @param listener The listener to remove. + */ public void removeClearedListener(ResourcesContainerClearedListener listener) { this.listeners.remove(listener); } + /** + * Clears all loaded spritesheets and notifies listeners of the clearing event. + */ public void clear() { this.loadedSpritesheets.clear(); listeners.forEach(ResourcesContainerClearedListener::cleared); } + /** + * Checks if a spritesheet with the specified name is loaded. + * + * @param name The name of the spritesheet. + * @return True if the spritesheet is loaded, false otherwise. + */ public boolean contains(String name) { return this.loadedSpritesheets.containsKey(name); } @@ -73,6 +105,12 @@ public Spritesheet get(final String path) { return this.loadedSpritesheets.get(name); // this already returns null if absent } + /** + * Gets a collection of spritesheets that match the specified predicate. + * + * @param pred The predicate to filter the spritesheets. + * @return A collection of spritesheets that match the predicate, or an empty collection if the predicate is null. + */ public Collection get(Predicate pred) { if (pred == null) { return new ArrayList<>(); @@ -81,22 +119,54 @@ public Collection get(Predicate pred) { return this.loadedSpritesheets.values().stream().filter(pred).toList(); } + /** + * Gets a collection of all loaded spritesheets. + * + * @return A collection of all loaded spritesheets. + */ public Collection getAll() { return this.loadedSpritesheets.values(); } + /** + * Gets the custom keyframe durations for the specified spritesheet name. + * + * @param name The name of the spritesheet. + * @return An array of custom keyframe durations, or an empty array if none are found. + */ public int[] getCustomKeyFrameDurations(final String name) { return this.customKeyFrameDurations.getOrDefault(FileUtilities.getFileName(name), new int[0]); } + /** + * Gets the custom keyframe durations for the specified spritesheet. + * + * @param sprite The spritesheet to get the custom keyframe durations for. + * @return An array of custom keyframe durations, or an empty array if none are found. + */ public int[] getCustomKeyFrameDurations(final Spritesheet sprite) { return getCustomKeyFrameDurations(sprite.getName()); } + /** + * Loads a spritesheet from the specified image, path, width, and height. + * + * @param image The image of the spritesheet. + * @param path The path of the spritesheet. + * @param spriteWidth The width of each sprite in the spritesheet. + * @param spriteHeight The height of each sprite in the spritesheet. + * @return The loaded spritesheet. + */ public Spritesheet load(final BufferedImage image, final String path, final int spriteWidth, final int spriteHeight) { return new Spritesheet(image, path, spriteWidth, spriteHeight); } + /** + * Loads a spritesheet from the specified tileset. + * + * @param tileset The tileset to load the spritesheet from. + * @return The loaded spritesheet, or null if the tileset or its image is null, or if the image's absolute source path is null. + */ public Spritesheet load(final ITileset tileset) { if (tileset == null || tileset.getImage() == null) { return null; @@ -110,6 +180,12 @@ public Spritesheet load(final ITileset tileset) { tileset.getTileDimension().width, tileset.getTileDimension().height); } + /** + * Loads a spritesheet from the specified spritesheet resource. + * + * @param info The spritesheet resource containing the information to load the spritesheet. + * @return The loaded spritesheet, or null if the image is null or empty. + */ public Spritesheet load(final SpritesheetResource info) { Spritesheet sprite; if (info.getImage() == null || info.getImage().isEmpty()) { @@ -170,6 +246,13 @@ public List loadFrom(final String spriteInfoFile) { return sprites; } + /** + * Saves the spritesheet information to the specified file. + * + * @param spriteInfoFile The path to the file where the spritesheet information will be saved. + * @param metadataOnly If true, only the metadata will be saved; if false, both the sprites and metadata will be saved. + * @return True if the spritesheet information was successfully saved, false otherwise. + */ public boolean saveTo(final String spriteInfoFile, boolean metadataOnly) { // get all spritesheets List allSpriteSheets = new ArrayList<>(getAll()); @@ -214,16 +297,36 @@ public boolean saveTo(final String spriteInfoFile, boolean metadataOnly) { } } + /** + * Loads a spritesheet from the specified path, width, and height. + * + * @param path The path of the spritesheet. + * @param spriteWidth The width of each sprite in the spritesheet. + * @param spriteHeight The height of each sprite in the spritesheet. + * @return The loaded spritesheet. + */ public Spritesheet load(final String path, final int spriteWidth, final int spriteHeight) { return new Spritesheet(Resources.images().get(path, true), path, spriteWidth, spriteHeight); } + /** + * Removes a spritesheet from the collection of loaded spritesheets. + * + * @param path The path of the spritesheet to remove. + * @return The removed spritesheet, or null if no spritesheet was found for the specified path. + */ public Spritesheet remove(final String path) { Spritesheet spriteToRemove = this.loadedSpritesheets.remove(path); customKeyFrameDurations.remove(path); return spriteToRemove; } + /** + * Updates a spritesheet with the specified resource information. + * + * @param info The resource information for the spritesheet to update. + * @return The updated spritesheet, or null if the resource information is invalid or the spritesheet could not be updated. + */ public Spritesheet update(final SpritesheetResource info) { if (info == null || info.getName() == null) { return null; @@ -241,6 +344,14 @@ public Spritesheet update(final SpritesheetResource info) { return null; } + /** + * Parses a line from the sprite info file and loads the corresponding spritesheet. + * + * @param baseDirectory The base directory of the sprite info file. + * @param sprites The list to which the loaded spritesheet will be added. + * @param items The list of items parsed from the line. + * @param parts The array of parts parsed from the line. + */ private void getSpriteSheetFromSpriteInfoLine(String baseDirectory, ArrayList sprites, List items, String[] parts) { try { final String name = baseDirectory + items.get(0); diff --git a/litiengine/src/main/java/de/gurkenlabs/litiengine/resources/Strings.java b/litiengine/src/main/java/de/gurkenlabs/litiengine/resources/Strings.java index a2f9298d8..2b71a4792 100644 --- a/litiengine/src/main/java/de/gurkenlabs/litiengine/resources/Strings.java +++ b/litiengine/src/main/java/de/gurkenlabs/litiengine/resources/Strings.java @@ -1,5 +1,6 @@ package de.gurkenlabs.litiengine.resources; +import de.gurkenlabs.litiengine.Game; import java.io.BufferedReader; import java.io.IOException; import java.io.InputStream; @@ -17,8 +18,10 @@ import java.util.logging.Level; import java.util.logging.Logger; -import de.gurkenlabs.litiengine.Game; - +/** + * This class provides methods to manage and retrieve localized strings from resource bundles. It supports different encodings and allows fetching + * strings with or without formatting arguments. + */ public final class Strings { public static final String DEFAULT_BUNDLE = "strings"; @@ -32,10 +35,21 @@ public final class Strings { Locale.setDefault(Locale.of("en", "US")); } + /** + * Sets the character encoding to be used for reading resource bundles. + * + * @param charset The character encoding to set. + */ public void setEncoding(Charset charset) { this.charset = charset; } + /** + * Retrieves the localized string for the specified key from the default resource bundle. + * + * @param key The key for the desired string. + * @return The localized string corresponding to the specified key, or null if the key is null. + */ public String get(final String key) { if (key == null) { return null; @@ -44,6 +58,13 @@ public String get(final String key) { return this.getFrom(DEFAULT_BUNDLE, key); } + /** + * Retrieves the localized string for the specified key from the default resource bundle, with optional formatting arguments. + * + * @param key The key for the desired string. + * @param args The arguments to format the string with. + * @return The localized string corresponding to the specified key, formatted with the provided arguments, or null if the key is null. + */ public String get(final String key, Object... args) { if (key == null) { return null; @@ -52,6 +73,15 @@ public String get(final String key, Object... args) { return this.getFrom(DEFAULT_BUNDLE, key, args); } + /** + * Retrieves the localized string for the specified key from the specified resource bundle, with optional formatting arguments. + * + * @param bundleName The name of the resource bundle to retrieve the string from. + * @param key The key for the desired string. + * @param args The arguments to format the string with. + * @return The localized string corresponding to the specified key, formatted with the provided arguments, or the key itself if the resource is not + * found. + */ public String getFrom(final String bundleName, final String key, Object... args) { if (bundleName == null || key == null) { return null; @@ -63,7 +93,7 @@ public String getFrom(final String bundleName, final String key, Object... args) String value = defaultBundle.getString(key); String decodedValue = - this.charset.equals(StandardCharsets.ISO_8859_1) ? value : new String(value.getBytes(StandardCharsets.ISO_8859_1), this.charset); + this.charset.equals(StandardCharsets.ISO_8859_1) ? value : new String(value.getBytes(StandardCharsets.ISO_8859_1), this.charset); if (args.length > 0) { return MessageFormat.format(decodedValue, args); } @@ -84,8 +114,7 @@ public String getFrom(final String bundleName, final String key, Object... args) * This method is not cached. Ever call will open up a new {@link InputStream} to read the strings from the text * file. * - * @param textFile - * The text file that will be retrieved. + * @param textFile The text file that will be retrieved. * @return A list with all strings that are contained by the text file. */ public String[] getList(String textFile) { @@ -117,10 +146,23 @@ public String[] getList(String textFile) { return new String[0]; } + /** + * Checks if the default resource bundle contains the specified key. + * + * @param key The key to check for. + * @return True if the key is found in the default resource bundle, false otherwise. + */ public boolean contains(final String key) { return contains(DEFAULT_BUNDLE, key); } + /** + * Checks if the specified resource bundle contains the specified key. + * + * @param bundleName The name of the resource bundle to check. + * @param key The key to check for. + * @return True if the key is found in the specified resource bundle, false otherwise. + */ public boolean contains(final String bundleName, final String key) { try { final ResourceBundle defaultBundle = ResourceBundle.getBundle(bundleName, Game.config().client().getLocale()); diff --git a/litiengine/src/main/java/de/gurkenlabs/litiengine/resources/TextureAtlas.java b/litiengine/src/main/java/de/gurkenlabs/litiengine/resources/TextureAtlas.java index ec9b6458f..d032f0594 100644 --- a/litiengine/src/main/java/de/gurkenlabs/litiengine/resources/TextureAtlas.java +++ b/litiengine/src/main/java/de/gurkenlabs/litiengine/resources/TextureAtlas.java @@ -1,10 +1,7 @@ package de.gurkenlabs.litiengine.resources; -import java.util.ArrayList; -import java.util.List; -import java.util.logging.Level; -import java.util.logging.Logger; - +import de.gurkenlabs.litiengine.util.io.FileUtilities; +import de.gurkenlabs.litiengine.util.io.XmlUtilities; import jakarta.xml.bind.JAXBException; import jakarta.xml.bind.annotation.XmlAttribute; import jakarta.xml.bind.annotation.XmlElement; @@ -12,10 +9,15 @@ import jakarta.xml.bind.annotation.XmlTransient; import jakarta.xml.bind.annotation.adapters.XmlAdapter; import jakarta.xml.bind.annotation.adapters.XmlJavaTypeAdapter; +import java.util.ArrayList; +import java.util.List; +import java.util.logging.Level; +import java.util.logging.Logger; -import de.gurkenlabs.litiengine.util.io.FileUtilities; -import de.gurkenlabs.litiengine.util.io.XmlUtilities; - +/** + * Represents a texture atlas, which is a collection of images packed into a single image. This class provides methods to read the texture atlas from + * an XML file and access its properties. + */ @XmlRootElement(name = "TextureAtlas") public class TextureAtlas { private static final Logger log = Logger.getLogger(TextureAtlas.class.getName()); @@ -34,10 +36,19 @@ public class TextureAtlas { private String absoluteImagePath; + /** + * Default constructor for the TextureAtlas class. This constructor is kept for serialization purposes. + */ TextureAtlas() { // keep for serialization } + /** + * Reads a TextureAtlas from the specified XML file. + * + * @param textureAtlasFile The path to the XML file containing the texture atlas data. + * @return The TextureAtlas object read from the file, or null if the file could not be read. + */ public static TextureAtlas read(String textureAtlasFile) { try { TextureAtlas atlas = XmlUtilities.read(TextureAtlas.class, Resources.getLocation(textureAtlasFile)); @@ -54,21 +65,41 @@ public static TextureAtlas read(String textureAtlasFile) { } } + /** + * Gets the absolute image path of the texture atlas. + * + * @return The absolute image path. + */ @XmlTransient public String getAbsoluteImagePath() { return this.absoluteImagePath; } + /** + * Gets the width of the texture atlas. + * + * @return The width of the texture atlas. + */ @XmlTransient public int getWidth() { return this.width; } + /** + * Gets the height of the texture atlas. + * + * @return The height of the texture atlas. + */ @XmlTransient public int getHeight() { return this.height; } + /** + * Gets the list of sprites in the texture atlas. If the list is null, it initializes a new empty list. + * + * @return The list of sprites. + */ @XmlTransient public List getSprites() { if (this.sprites == null) { @@ -78,6 +109,12 @@ public List getSprites() { return this.sprites; } + /** + * Retrieves a sprite by its name from the texture atlas. + * + * @param name The name of the sprite to retrieve. + * @return The sprite with the specified name, or null if no such sprite exists. + */ public Sprite getSprite(String name) { if (name == null || name.isEmpty()) { return null; @@ -86,22 +123,45 @@ public Sprite getSprite(String name) { return this.getSprites().stream().filter(x -> x.getName().equals(name)).findFirst().orElse(null); } + /** + * Sets the image path for the texture atlas. + * + * @param imagePath The new image path to set. + */ public void setImagePath(String imagePath) { this.rawImagePath = imagePath; } + /** + * Sets the width of the texture atlas. + * + * @param width The new width to set. + */ public void setWidth(int width) { this.width = width; } + /** + * Sets the height of the texture atlas. + * + * @param height The new height to set. + */ public void setHeight(int height) { this.height = height; } + /** + * Sets the list of sprites in the texture atlas. + * + * @param sprites The new list of sprites to set. + */ public void setSprites(List sprites) { this.sprites = sprites; } + /** + * Represents a sprite in the texture atlas. This class contains properties such as name, position, dimensions, and rotation status of the sprite. + */ @XmlRootElement(name = "sprite") public static class Sprite { @XmlAttribute(name = "n") @@ -129,85 +189,178 @@ public static class Sprite { @XmlJavaTypeAdapter(CustomBooleanAdapter.class) private Boolean rotated; + /** + * Default constructor for the Sprite class. This constructor is kept for serialization purposes. + */ Sprite() { // keep for serialization } + /** + * Gets the name of the sprite. + * + * @return The name of the sprite. + */ @XmlTransient public String getName() { return this.name; } + /** + * Gets the x-coordinate of the sprite. + * + * @return The x-coordinate of the sprite. + */ @XmlTransient public int getX() { return this.x; } + /** + * Gets the y-coordinate of the sprite. + * + * @return The y-coordinate of the sprite. + */ @XmlTransient public int getY() { return this.y; } + /** + * Gets the width of the sprite. + * + * @return The width of the sprite. + */ @XmlTransient public int getWidth() { return this.width; } + /** + * Gets the height of the sprite. + * + * @return The height of the sprite. + */ @XmlTransient public int getHeight() { return this.height; } + /** + * Gets the x-offset of the sprite. + * + * @return The x-offset of the sprite. + */ @XmlTransient public int getOffsetX() { return this.offsetX; } + /** + * Gets the y-offset of the sprite. + * + * @return The y-offset of the sprite. + */ @XmlTransient public int getOffsetY() { return this.offsetY; } + /** + * Checks if the sprite is rotated. + * + * @return True if the sprite is rotated, false otherwise. + */ @XmlTransient public boolean isRotated() { return this.rotated != null && this.rotated; } + /** + * Sets the name of the sprite. + * + * @param name The new name to set. + */ public void setName(String name) { this.name = name; } + /** + * Sets the x-coordinate of the sprite. + * + * @param x The new x-coordinate to set. + */ public void setX(int x) { this.x = x; } + /** + * Sets the y-coordinate of the sprite. + * + * @param y The new y-coordinate to set. + */ public void setY(int y) { this.y = y; } + /** + * Sets the width of the sprite. + * + * @param width The new width to set. + */ public void setWidth(int width) { this.width = width; } + /** + * Sets the height of the sprite. + * + * @param height The new height to set. + */ public void setHeight(int height) { this.height = height; } + /** + * Sets the x-offset of the sprite. + * + * @param offsetX The new x-offset to set. + */ public void setOffsetX(int offsetX) { this.offsetX = offsetX; } + /** + * Sets the y-offset of the sprite. + * + * @param offsetY The new y-offset to set. + */ public void setOffsetY(int offsetY) { this.offsetY = offsetY; } + /** + * Sets the rotation status of the sprite. + * + * @param rotated The new rotation status to set. + */ public void setRotated(boolean rotated) { this.rotated = rotated; } } + /** + * Custom adapter to convert between String and Boolean values for XML serialization. This adapter interprets "y", "yes", "1", and "true" + * (case-insensitive) as true, and any other value as false. + */ public static class CustomBooleanAdapter extends XmlAdapter { - + /** + * Converts a String value to a Boolean. + * + * @param v The String value to convert. + * @return The Boolean representation of the String value. + * @throws Exception If an error occurs during conversion. + */ @Override public Boolean unmarshal(String v) throws Exception { if (v == null || v.isEmpty()) { @@ -217,9 +370,16 @@ public Boolean unmarshal(String v) throws Exception { return v.equalsIgnoreCase("y") || v.equalsIgnoreCase("yes") || v.equals("1") || v.equalsIgnoreCase("true"); } + /** + * Converts a Boolean value to a String. + * + * @param v The Boolean value to convert. + * @return The String representation of the Boolean value. + * @throws Exception If an error occurs during conversion. + */ @Override public String marshal(Boolean v) throws Exception { - return v.booleanValue() ? "y" : "n"; + return v ? "y" : "n"; } } } diff --git a/litiengine/src/main/java/de/gurkenlabs/litiengine/resources/Tilesets.java b/litiengine/src/main/java/de/gurkenlabs/litiengine/resources/Tilesets.java index bf11dbb76..8b7d6a109 100644 --- a/litiengine/src/main/java/de/gurkenlabs/litiengine/resources/Tilesets.java +++ b/litiengine/src/main/java/de/gurkenlabs/litiengine/resources/Tilesets.java @@ -1,24 +1,39 @@ package de.gurkenlabs.litiengine.resources; -import java.io.IOException; -import java.net.URISyntaxException; -import java.net.URL; - -import jakarta.xml.bind.JAXBException; - import de.gurkenlabs.litiengine.environment.tilemap.xml.Tileset; import de.gurkenlabs.litiengine.environment.tilemap.xml.TmxException; import de.gurkenlabs.litiengine.util.io.XmlUtilities; +import jakarta.xml.bind.JAXBException; +import java.io.IOException; +import java.net.URISyntaxException; +import java.net.URL; +/** + * Manages the loading and storage of Tileset resources. + */ public class Tilesets extends ResourcesContainer { - Tilesets() {} + /** + * Default constructor for the Tilesets class. This constructor is kept for serialization purposes. + */ + Tilesets() { + } + /** + * Loads a Tileset from the specified URL. + * + * @param resourceName The URL of the resource to load. + * @return The loaded Tileset. + * @throws IOException If an I/O error occurs. + * @throws URISyntaxException If the URL is not formatted correctly. + */ @Override protected Tileset load(URL resourceName) throws IOException, URISyntaxException { try { Tileset tileset = XmlUtilities.read(Tileset.class, resourceName); - tileset.finish(resourceName); + if (tileset != null) { + tileset.finish(resourceName); + } return tileset; } catch (JAXBException e) { throw new TmxException(e);