World File Parsing

.github/workflows/rust.yml

@@ -27,10 +27,10 @@ jobs:
       run: sudo apt-get install -y libsfml-dev libcsfml-dev libasound2-dev libudev-dev
 
     - name: Build library
-      run: cargo build --lib --verbose
+      run: cargo build --lib --all-features --verbose
 
     - name: Run tests
-      run: cargo test --verbose
+      run: cargo test --all-features --verbose
 
   rustfmt:
     runs-on: ubuntu-24.04

CHANGELOG.md

@@ -5,6 +5,10 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.14.0]
+### Added
+- Added a new crate feature `world` to enable support for parsing `World` files.
+
 ## [0.13.0]
 ### Added
 - Added a `source` member to `Tileset`, `Map` and `Template`, which stores the resource path they have been loaded from. (#303)

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "tiled"
-version = "0.13.0"
+version = "0.14.0"
 description = "A rust crate for loading maps created by the Tiled editor"
 categories = ["game-development"]
 keywords = ["gamedev", "tiled", "tmx", "map"]
@@ -14,6 +14,7 @@ include = ["src/**/*.rs", "README.md", "LICENSE", "CHANGELOG.md"]
 [features]
 default = ["zstd"]
 wasm = ["zstd/wasm"]
+world = ["regex", "serde", "serde_json", "serde_regex"]
 
 [lib]
 name = "tiled"
@@ -36,6 +37,10 @@ base64 = "0.22.1"
 xml-rs = "0.8.4"
 zstd = { version = "0.13.1", optional = true, default-features = false }
 flate2 = "1.0.28"
+serde = { version = "1.0.216", optional = true }
+serde_json = { version = "1.0.133", optional = true }
+serde_regex = { version = "1.1.0", optional = true }
+regex = { version = "1.11.1", optional = true }
 
 [dev-dependencies.sfml]
 version = "0.21.0"

README.md

@@ -52,7 +52,7 @@ let mut loader = Loader::with_reader(
     // Doing this embedding is useful for places where the OS filesystem is not available (e.g. WASM applications).
     |path: &std::path::Path| -> std::io::Result<_> {
         if path == std::path::Path::new("/my-map.tmx") {
-            Ok(std::io::Cursor::new(include_bytes!("../assets/tiled_csv.tmx")))
+            Ok(std::io::Cursor::new(include_bytes!("assets/tiled_csv.tmx")))
         } else {
             Err(std::io::ErrorKind::NotFound.into())
         }
@@ -86,7 +86,7 @@ impl tiled::ResourceReader for MyReader {
     // really dumb example implementation that just keeps resources in memory
     fn read_from(&mut self, path: &std::path::Path) -> std::result::Result<Self::Resource, Self::Error> {
         if path == std::path::Path::new("my_map.tmx") {
-            Ok(Cursor::new(include_bytes!("../assets/tiled_xml.tmx")))
+            Ok(Cursor::new(include_bytes!("assets/tiled_xml.tmx")))
         } else {
             Err(std::io::Error::new(std::io::ErrorKind::NotFound, "file not found"))
         }

assets/world/world_basic.world

@@ -0,0 +1,20 @@
+{
+    "maps": [
+        {
+            "fileName": "map01.tmx",
+            "height": 640,
+            "width": 960,
+            "x": 0,
+            "y": 0
+        },
+        {
+            "fileName": "map02.tmx",
+            "height": 640,
+            "width": 960,
+            "x": 960,
+            "y": 0
+        }
+    ],
+    "onlyShowAdjacentMaps": false,
+    "type": "world"
+}

assets/world/world_pattern.world

@@ -0,0 +1,26 @@
+{
+    "patterns": [
+        {
+            "regexp": "map-x0*(\\d+)-y0*(\\d+)-.*\\.tmx",
+            "multiplierX": 640,
+            "multiplierY": 480,
+            "offsetX": 240,
+            "offsetY": -240
+        },
+        {
+            "regexp": "overworld-x0*(\\d+)-y0*(\\d+).tmx",
+            "multiplierX": 640,
+            "multiplierY": 480,
+            "offsetX": 4192,
+            "offsetY": 4192            
+        },
+        {
+            "regexp": "OVERFLOW-x0*(\\d+)-y0*(\\d+).tmx",
+            "multiplierX": 50000000,
+            "multiplierY": 50000000,
+            "offsetX": 4192,
+            "offsetY": 4192    
+        }
+    ],
+    "type": "world"
+}

src/error.rs

@@ -57,6 +57,17 @@ pub enum Error {
     CsvDecodingError(CsvDecodingError),
     /// An error occurred when parsing an XML file, such as a TMX or TSX file.
     XmlDecodingError(xml::reader::Error),
+    #[cfg(feature = "world")]
+    /// An error occurred when attempting to deserialize a JSON file.
+    JsonDecodingError(serde_json::Error),
+    #[cfg(feature = "world")]
+    /// Filename does not match any pattern in the world file.
+    NoMatchFound {
+        /// The filename that was not matched.
+        path: PathBuf,
+    },
+    /// A parameter is out of range or results in arithmetic underflow or overflow.
+    RangeError(String),
     /// The XML stream ended before the document was fully parsed.
     PrematureEnd(String),
     /// The path given is invalid because it isn't contained in any folder.
@@ -120,6 +131,13 @@ impl fmt::Display for Error {
             Error::Base64DecodingError(e) => write!(fmt, "{}", e),
             Error::CsvDecodingError(e) => write!(fmt, "{}", e),
             Error::XmlDecodingError(e) => write!(fmt, "{}", e),
+            #[cfg(feature = "world")]
+            Error::JsonDecodingError(e) => write!(fmt, "{}", e),
+            #[cfg(feature = "world")]
+            Error::NoMatchFound { path } => {
+                write!(fmt, "No match found for path: '{}'", path.to_string_lossy())
+            }
+            Error::RangeError(e) => write!(fmt, "Range error: {}", e),
             Error::PrematureEnd(e) => write!(fmt, "{}", e),
             Error::PathIsNotFile => {
                 write!(

src/lib.rs

@@ -20,6 +20,8 @@ mod template;
 mod tile;
 mod tileset;
 mod util;
+#[cfg(feature = "world")]
+mod world;
 
 pub use animation::*;
 pub use cache::*;
@@ -34,3 +36,5 @@ pub use reader::*;
 pub use template::*;
 pub use tile::*;
 pub use tileset::*;
+#[cfg(feature = "world")]
+pub use world::*;

src/loader.rs

@@ -5,6 +5,9 @@ use crate::{
     Tileset,
 };
 
+#[cfg(feature = "world")]
+use crate::World;
+
 /// A type used for loading [`Map`]s and [`Tileset`]s.
 ///
 /// Internally, it holds a [`ResourceCache`] that, as its name implies, caches intermediate loading
@@ -182,6 +185,18 @@ impl<Cache: ResourceCache, Reader: ResourceReader> Loader<Cache, Reader> {
         crate::parse::xml::parse_tileset(path.as_ref(), &mut self.reader, &mut self.cache)
     }
 
+    #[cfg(feature = "world")]
+    /// Parses a file hopefully containing a Tiled world.
+    ///
+    /// The returned [`World`] provides the deserialized data from the world file. It does not load
+    /// any maps or tilesets.
+    /// ## Note
+    /// The ['WorldPattern`] struct provides [`WorldPattern::capture_path`] and [`WorldPattern::capture_paths`]
+    /// as utility functions to test paths and return parsed [`WorldMap`]s.
+    pub fn load_world(&mut self, path: impl AsRef<Path>) -> Result<World> {
+        crate::world::parse_world(path.as_ref(), &mut self.reader)
+    }
+
     /// Returns a reference to the loader's internal [`ResourceCache`].
     pub fn cache(&self) -> &Cache {
         &self.cache

src/world.rs

@@ -0,0 +1,158 @@
+use std::{
+    io::Read,
+    path::{Path, PathBuf},
+};
+
+use regex::Regex;
+use serde::Deserialize;
+
+use crate::{Error, ResourceReader};
+
+/// A World is a list of maps files or regex patterns that define a layout of TMX maps.
+/// You can use the loader to further load the maps defined by the world.
+#[derive(Deserialize, PartialEq, Clone, Debug)]
+pub struct World {
+    /// The path first used in a [`ResourceReader`] to load this world.
+    #[serde(skip_deserializing)]
+    pub source: PathBuf,
+    /// The [`WorldMap`]s defined by the world file.
+    pub maps: Option<Vec<WorldMap>>,
+    /// Optional regex pattern to load maps.
+    pub patterns: Option<Vec<WorldPattern>>,
+}
+
+impl World {
+    /// Utility function to test a single path against all defined patterns.
+    /// Returns a parsed [`WorldMap`] on the first matched pattern or an error if no patterns match.
+    pub fn match_path(&self, path: impl AsRef<Path>) -> Result<WorldMap, Error> {
+        if let Some(patterns) = &self.patterns {
+            for pattern in patterns {
+                let captures = match pattern.regexp.captures(path.as_ref().to_str().unwrap()) {
+                    Some(captures) => captures,
+                    None => continue,
+                };
+
+                let x = match captures.get(1) {
+                    Some(x) => x.as_str().parse::<i32>().unwrap(),
+                    None => continue,
+                };
+
+                let y = match captures.get(2) {
+                    Some(y) => y.as_str().parse::<i32>().unwrap(),
+                    None => continue,
+                };
+
+                // Calculate x and y positions based on the multiplier and offset.
+                let x = x
+                    .checked_mul(pattern.multiplier_x)
+                    .ok_or(Error::RangeError(
+                        "Capture x * multiplierX causes overflow".to_string(),
+                    ))?
+                    .checked_add(pattern.offset_x)
+                    .ok_or(Error::RangeError(
+                        "Capture x * multiplierX + offsetX causes overflow".to_string(),
+                    ))?;
+
+                let y = y
+                    .checked_mul(pattern.multiplier_y)
+                    .ok_or(Error::RangeError(
+                        "Capture y * multiplierY causes overflow".to_string(),
+                    ))?
+                    .checked_add(pattern.offset_y)
+                    .ok_or(Error::RangeError(
+                        "Capture y * multiplierY + offsetY causes overflow".to_string(),
+                    ))?;
+
+                // Returning the first matched pattern aligns with how Tiled handles patterns.
+                return Ok(WorldMap {
+                    filename: path.as_ref().to_str().unwrap().to_string(),
+                    x,
+                    y,
+                    width: None,
+                    height: None,
+                });
+            }
+        }
+
+        Err(Error::NoMatchFound {
+            path: path.as_ref().to_owned(),
+        })
+    }
+
+    /// Utility function to test a vec of filenames against all defined patterns.
+    /// Returns a vec of results with the parsed [`WorldMap`]s if it matches the pattern.
+    pub fn match_paths<P: AsRef<Path>>(&self, paths: &[P]) -> Vec<Result<WorldMap, Error>> {
+        paths
+            .into_iter()
+            .map(|path| self.match_path(path))
+            .collect()
+    }
+}
+
+/// A WorldMap provides the information for a map in the world and its layout.
+#[derive(Deserialize, PartialEq, Clone, Debug)]
+pub struct WorldMap {
+    /// The filename of the tmx map.
+    #[serde(rename = "fileName")]
+    pub filename: String,
+    /// The x position of the map.
+    pub x: i32,
+    /// The y position of the map.
+    pub y: i32,
+    /// The optional width of the map.
+    pub width: Option<i32>,
+    /// The optional height of the map.
+    pub height: Option<i32>,
+}
+
+/// A WorldPattern defines a regex pattern to automatically determine which maps to load and how to lay them out.
+#[derive(Deserialize, Clone, Debug)]
+#[serde(rename_all = "camelCase")]
+pub struct WorldPattern {
+    /// The regex pattern to match against filenames.
+    /// The first two capture groups should be the x integer and y integer positions.
+    #[serde(with = "serde_regex")]
+    pub regexp: Regex,
+    /// The multiplier for the x position.
+    pub multiplier_x: i32,
+    /// The multiplier for the y position.
+    pub multiplier_y: i32,
+    /// The offset for the x position.
+    pub offset_x: i32,
+    /// The offset for the y position.
+    pub offset_y: i32,
+}
+
+impl PartialEq for WorldPattern {
+    fn eq(&self, other: &Self) -> bool {
+        self.multiplier_x == other.multiplier_x
+            && self.multiplier_y == other.multiplier_y
+            && self.offset_x == other.offset_x
+            && self.offset_y == other.offset_y
+            && self.regexp.to_string() == other.regexp.to_string()
+    }
+}
+
+pub(crate) fn parse_world(
+    world_path: &Path,
+    reader: &mut impl ResourceReader,
+) -> Result<World, Error> {
+    let mut path = reader
+        .read_from(&world_path)
+        .map_err(|err| Error::ResourceLoadingError {
+            path: world_path.to_owned(),
+            err: Box::new(err),
+        })?;
+
+    let mut world_string = String::new();
+    path.read_to_string(&mut world_string)
+        .map_err(|err| Error::ResourceLoadingError {
+            path: world_path.to_owned(),
+            err: Box::new(err),
+        })?;
+
+    let world: World =
+        serde_json::from_str(&world_string).map_err(|err| Error::JsonDecodingError(err))?;
+
+    Ok(world)
+}