use of C++23 code

Signed-off-by: Peter Siegmund <mars3142@noreply.mars3142.dev>

components/cartridge/CMakeLists.txt

@@ -0,0 +1,37 @@
+set(CARTRIDGE_VERSION_MAJOR 1)
+set(CARTRIDGE_VERSION_MINOR 0)
+set(CARTRIDGE_VERSION_PATCH 0)
+set(CARTRIDGE_VERSION "${CARTRIDGE_VERSION_MAJOR}.${CARTRIDGE_VERSION_MINOR}.${CARTRIDGE_VERSION_PATCH}")
+
+configure_file(
+    ${CMAKE_CURRENT_SOURCE_DIR}/version.h.in
+    ${CMAKE_CURRENT_BINARY_DIR}/include/cartridge/version.h
+    @ONLY
+)
+
+set(CARTRIDGE_SRC
+        src/binary_reader.cpp
+        src/cartridge.cpp
+        src/lat_lng.cpp
+        src/media.cpp
+        src/parser.cpp
+)
+
+add_library(cartridge SHARED ${CARTRIDGE_SRC})
+set_target_properties(cartridge PROPERTIES
+        VERSION ${CARTRIDGE_VERSION}
+        SOVERSION ${CARTRIDGE_VERSION_MAJOR}
+        CXX_STANDARD 23
+        CXX_STANDARD_REQUIRED ON
+)
+
+target_include_directories(cartridge
+        PUBLIC
+        ${CMAKE_CURRENT_SOURCE_DIR}/include
+        ${CMAKE_CURRENT_BINARY_DIR}/include
+)
+
+target_link_libraries(cartridge
+        PRIVATE
+        storage
+)

components/cartridge/include/cartridge/binary_reader.h

@@ -0,0 +1,74 @@
+// MIT License
+// Copyright (c) 2026 by Peter Siegmund (mars3142)
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
+
+#pragma once
+#include <cstdint>
+#include <stdexcept>
+#include <string>
+#include <vector>
+#include <span>
+
+namespace cartridge {
+
+enum class SeekOrigin { Begin, Current, End };
+
+enum class Endian { Little, Big };
+
+class BinaryReader {
+public:
+  explicit BinaryReader(std::span<const uint8_t> data,
+                        Endian endian = Endian::Little);
+
+  void seek(int offset, SeekOrigin origin);
+  [[nodiscard]] uint8_t getByte();
+  [[nodiscard]] int16_t getShort();
+  [[nodiscard]] uint16_t getUShort();
+  [[nodiscard]] int32_t getLong();
+  [[nodiscard]] uint32_t getULong();
+  [[nodiscard]] double getDouble();
+  [[nodiscard]] std::string getASCIIZ();
+  [[nodiscard]] std::span<const uint8_t> data() const { return _data; }
+
+private:
+  template <typename T> [[nodiscard]] T readInt(size_t size);
+  [[nodiscard]] static bool isSystemLittleEndian();
+  static void swapBytes(uint8_t *data, size_t size);
+
+  std::span<const uint8_t> _data;
+  Endian _endian;
+  size_t _index;
+};
+
+template <typename T> T BinaryReader::readInt(const size_t size) {
+  if (_index + size > _data.size())
+    throw std::out_of_range("readInt out of range");
+  T value = 0;
+  if (_endian == Endian::Little) {
+    for (size_t i = 0; i < size; ++i) {
+      value |= static_cast<T>(_data[_index + i]) << (8 * i);
+    }
+  } else {
+    for (size_t i = 0; i < size; ++i) {
+      value = (value << 8) | _data[_index + i];
+    }
+  }
+  _index += size;
+  return value;
+}
+
+} // namespace cartridge

components/cartridge/include/cartridge/cartridge.h

@@ -0,0 +1,94 @@
+// MIT License
+// Copyright (c) 2026 by Peter Siegmund (mars3142)
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
+
+#pragma once
+
+#include "cartridge/binary_reader.h"
+#include "cartridge/lat_lng.h"
+#include "cartridge/media.h"
+#include <map>
+#include <memory>
+#include <string>
+#include <vector>
+
+namespace cartridge {
+
+class Cartridge {
+public:
+  // Factory method to create Cartridge from BinaryReader
+  static std::unique_ptr<Cartridge> create(BinaryReader &reader);
+
+  // Getters
+  [[nodiscard]] double altitude() const;
+  [[nodiscard]] const std::string &author() const;
+  [[nodiscard]] const LatLng &latLng() const;
+  [[nodiscard]] const std::string &cartridgeName() const;
+  [[nodiscard]] const std::string &cartridgeDesc() const;
+  [[nodiscard]] const std::string &cartridgeGuid() const;
+  [[nodiscard]] const std::string &typeOfCartridge() const;
+  [[nodiscard]] const std::string &playerName() const;
+  [[nodiscard]] const std::string &startLocationDesc() const;
+  [[nodiscard]] const std::string &version() const;
+  [[nodiscard]] const std::string &company() const;
+  [[nodiscard]] const std::string &recommendDevice() const;
+  [[nodiscard]] const std::string &completionCode() const;
+
+  // Media methods
+  std::unique_ptr<Media> getMedia(int objectId);
+  [[nodiscard]] int mediaCount() const;
+  std::unique_ptr<Media> splashScreen();
+  std::unique_ptr<Media> smallIcon();
+  std::unique_ptr<Media> luac();
+
+  // Comparison operators
+  bool operator==(const Cartridge &other) const;
+  bool operator!=(const Cartridge &other) const;
+
+  Cartridge(std::string cartridgeGuid, double altitude, std::string author,
+            std::string cartridgeDesc, std::string cartridgeName,
+            std::string company, std::string completionCode, LatLng latLng,
+            std::string playerName, std::string recommendDevice,
+            int smallIconId, int splashScreenId, std::string startLocationDesc,
+            std::string typeOfCartridge, std::string version,
+            std::map<int, int> references, std::vector<uint8_t> bytes);
+
+private:
+  // Fields
+  std::string m_cartridgeGuid;
+  double m_altitude;
+  std::string m_author;
+  std::string m_cartridgeDesc;
+  std::string m_cartridgeName;
+  std::string m_company;
+  std::string m_completionCode;
+  LatLng m_latLng;
+  std::string m_playerName;
+  std::string m_recommendDevice;
+  int m_smallIconId;
+  int m_splashScreenId;
+  std::string m_startLocationDesc;
+  std::string m_typeOfCartridge;
+  std::string m_version;
+  std::map<int, int> m_references;
+  std::vector<uint8_t> m_bytes;
+
+  int m_lastObject = -1;
+  std::unique_ptr<Media> m_lastMedia;
+};
+
+} // namespace cartridge

components/cartridge/include/cartridge/lat_lng.h

@@ -0,0 +1,36 @@
+// MIT License
+// Copyright (c) 2026 by Peter Siegmund (mars3142)
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
+
+#pragma once
+
+#include <string>
+
+namespace cartridge {
+class LatLng {
+  double m_latitude;
+  double m_longitude;
+
+  static std::string _format(double value, const std::string& suffix);
+
+ public:
+  LatLng(double latitude, double longitude);
+  [[nodiscard]] std::string latitude() const;
+  [[nodiscard]] std::string longitude() const;
+  [[nodiscard]] std::string toString() const;
+};
+}

components/cartridge/include/cartridge/media.h

@@ -0,0 +1,66 @@
+// MIT License
+// Copyright (c) 2026 by Peter Siegmund (mars3142)
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
+
+#pragma once
+
+#include "cartridge/binary_reader.h"
+#include <memory>
+#include <string>
+#include <vector>
+
+namespace cartridge {
+
+enum class ObjectType {
+  Deleted = -1,
+  Luac = 0,
+  Bmp = 1,
+  Png = 2,
+  Jpg = 3,
+  Gif = 4,
+  Wav = 17,
+  Mp3 = 18,
+  Fdl = 19,
+  Snd = 20,
+  Ogg = 21,
+  Swf = 33,
+  Txt = 49,
+  Invalid = -9999
+};
+
+class Media {
+public:
+  Media(std::string objectType, const std::vector<uint8_t> &data);
+
+  static std::unique_ptr<Media> create(BinaryReader &reader, int objectId,
+                                       int address);
+
+  bool operator==(const Media &other) const;
+  [[nodiscard]] std::size_t hash() const;
+
+  [[nodiscard]] const std::vector<uint8_t> &getData() const { return data; }
+  [[nodiscard]] const std::string &getObjectType() const { return objectType; }
+
+private:
+  static std::vector<uint8_t> readMediaData(BinaryReader &reader);
+  static std::string getObjectTypeString(int objectType);
+
+  std::string objectType;
+  std::vector<uint8_t> data;
+};
+
+} // namespace cartridge

components/cartridge/include/cartridge/parser.h

@@ -0,0 +1,28 @@
+// MIT License
+// Copyright (c) 2026 by Peter Siegmund (mars3142)
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+
+#pragma once
+
+#include <memory>
+#include <string>
+#include <vector>
+
+#include "cartridge/cartridge.h"
+
+namespace cartridge {
+
+std::unique_ptr<Cartridge> parseData(const std::vector<uint8_t>& bytes);
+
+std::unique_ptr<Cartridge> parseFile(const std::string& filePath);
+
+std::unique_ptr<Cartridge> parseCartridge();
+
+}  // namespace cartridge

components/cartridge/src/binary_reader.cpp

@@ -0,0 +1,90 @@
+// MIT License
+// Copyright (c) 2026 by Peter Siegmund (mars3142)
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
+
+#include "cartridge/binary_reader.h"
+
+#include <algorithm>
+#include <bit>
+#include <cstring>
+
+namespace cartridge {
+
+BinaryReader::BinaryReader(std::span<const uint8_t> data,
+                           const Endian endian)
+    : _data(data), _endian(endian), _index(0) {}
+
+void BinaryReader::seek(const int offset, const SeekOrigin origin) {
+  switch (origin) {
+  case SeekOrigin::Begin:
+    _index = offset;
+    break;
+  case SeekOrigin::Current:
+    _index += offset;
+    break;
+  case SeekOrigin::End:
+    _index = _data.size() - offset;
+    break;
+  }
+}
+
+uint8_t BinaryReader::getByte() {
+  if (_index >= _data.size())
+    throw std::out_of_range("getByte out of range");
+  return _data[_index++];
+}
+
+int16_t BinaryReader::getShort() { return readInt<int16_t>(2); }
+
+uint16_t BinaryReader::getUShort() { return readInt<uint16_t>(2); }
+
+int32_t BinaryReader::getLong() { return readInt<int32_t>(4); }
+
+uint32_t BinaryReader::getULong() { return readInt<uint32_t>(4); }
+
+double BinaryReader::getDouble() {
+  if (_index + 8 > _data.size())
+    throw std::out_of_range("getDouble out of range");
+  double value;
+  std::memcpy(&value, &_data[_index], 8);
+  if ((_endian == Endian::Little) != isSystemLittleEndian()) {
+    swapBytes(reinterpret_cast<uint8_t *>(&value), 8);
+  }
+  _index += 8;
+  return value;
+}
+
+std::string BinaryReader::getASCIIZ() {
+  std::string result;
+  uint8_t byte = 0;
+  do {
+    byte = getByte();
+    if (byte != 0)
+      result += static_cast<char>(byte);
+  } while (byte != 0);
+  return result;
+}
+
+bool BinaryReader::isSystemLittleEndian() {
+  return std::endian::native == std::endian::little;
+}
+
+void BinaryReader::swapBytes(uint8_t *data, size_t size) {
+  std::ranges::reverse(data, data + size);
+}
+
+} // namespace cartridge

components/cartridge/src/cartridge.cpp

@@ -0,0 +1,148 @@
+// MIT License
+// Copyright (c) 2026 by Peter Siegmund (mars3142)
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
+
+#include "cartridge/cartridge.h"
+#include "cartridge/binary_reader.h"
+#include "cartridge/lat_lng.h"
+#include "cartridge/media.h"
+
+namespace cartridge {
+
+Cartridge::Cartridge(std::string cartridgeGuid, double altitude,
+                     std::string author, std::string cartridgeDesc,
+                     std::string cartridgeName, std::string company,
+                     std::string completionCode, LatLng latLng,
+                     std::string playerName, std::string recommendDevice,
+                     int smallIconId, int splashScreenId,
+                     std::string startLocationDesc, std::string typeOfCartridge,
+                     std::string version, std::map<int, int> references,
+                     std::vector<uint8_t> bytes)
+    : m_cartridgeGuid(std::move(cartridgeGuid)), m_altitude(altitude),
+      m_author(std::move(author)), m_cartridgeDesc(std::move(cartridgeDesc)),
+      m_cartridgeName(std::move(cartridgeName)), m_company(std::move(company)),
+      m_completionCode(std::move(completionCode)), m_latLng(latLng),
+      m_playerName(std::move(playerName)),
+      m_recommendDevice(std::move(recommendDevice)), m_smallIconId(smallIconId),
+      m_splashScreenId(splashScreenId),
+      m_startLocationDesc(std::move(startLocationDesc)),
+      m_typeOfCartridge(std::move(typeOfCartridge)),
+      m_version(std::move(version)), m_references(std::move(references)),
+      m_bytes(std::move(bytes)) {}
+
+std::unique_ptr<Cartridge> Cartridge::create(BinaryReader &reader) {
+  try {
+    const uint16_t count = reader.getUShort();
+    std::map<int, int> references;
+    for (uint16_t index = 0; index < count; ++index) {
+      const int objectId = reader.getShort();
+      const int address = reader.getLong();
+      references.emplace(objectId, address);
+    }
+
+    reader.getLong(); // header length
+    const double latitude = reader.getDouble();
+    const double longitude = reader.getDouble();
+    const double altitude = reader.getDouble();
+    reader.getLong(); // unknown 0
+    reader.getLong(); // unknown 1
+    const int splashScreenId = reader.getShort();
+    const int smallIconId = reader.getShort();
+    const std::string typeOfCartridge = reader.getASCIIZ();
+    const std::string playerName = reader.getASCIIZ();
+    reader.getLong(); // unknown 2
+    reader.getLong(); // unknown 3
+    const std::string cartridgeName = reader.getASCIIZ();
+    const std::string cartridgeGuid = reader.getASCIIZ();
+    const std::string cartridgeDesc = reader.getASCIIZ();
+    const std::string startLocationDesc = reader.getASCIIZ();
+    const std::string version = reader.getASCIIZ();
+    const std::string author = reader.getASCIIZ();
+    const std::string company = reader.getASCIIZ();
+    const std::string recommendedDevice = reader.getASCIIZ();
+    reader.getLong(); // unknown 4
+    const std::string completionCode = reader.getASCIIZ();
+
+    // Rohdaten aus dem Reader extrahieren
+    const auto bytes_span = reader.data();
+    const std::vector<uint8_t> bytes(bytes_span.begin(), bytes_span.end());
+
+    return std::make_unique<Cartridge>(
+        cartridgeGuid, altitude, author, cartridgeDesc, cartridgeName, company,
+        completionCode, LatLng(latitude, longitude), playerName,
+        recommendedDevice, smallIconId, splashScreenId, startLocationDesc,
+        typeOfCartridge, version, references, bytes);
+  } catch (const std::exception &) {
+    return nullptr;
+  }
+}
+
+double Cartridge::altitude() const { return m_altitude; }
+const std::string &Cartridge::author() const { return m_author; }
+const LatLng &Cartridge::latLng() const { return m_latLng; }
+const std::string &Cartridge::cartridgeName() const { return m_cartridgeName; }
+const std::string &Cartridge::cartridgeDesc() const { return m_cartridgeDesc; }
+const std::string &Cartridge::cartridgeGuid() const { return m_cartridgeGuid; }
+const std::string &Cartridge::typeOfCartridge() const {
+  return m_typeOfCartridge;
+}
+const std::string &Cartridge::playerName() const { return m_playerName; }
+const std::string &Cartridge::startLocationDesc() const {
+  return m_startLocationDesc;
+}
+const std::string &Cartridge::version() const { return m_version; }
+const std::string &Cartridge::company() const { return m_company; }
+const std::string &Cartridge::recommendDevice() const {
+  return m_recommendDevice;
+}
+const std::string &Cartridge::completionCode() const { return m_completionCode; }
+
+std::unique_ptr<Media> Cartridge::getMedia(const int objectId) {
+  if (m_lastObject == objectId && m_lastMedia) {
+    return std::make_unique<Media>(*m_lastMedia);
+  }
+  if (auto it = m_references.find(objectId); it != m_references.end()) {
+    const int address = it->second;
+    BinaryReader reader(m_bytes, Endian::Little);
+    auto media = Media::create(reader, objectId, address);
+    if (media && media->getData().size() < 128000) {
+      m_lastObject = objectId;
+      m_lastMedia = std::make_unique<Media>(*media);
+    }
+    return media;
+  }
+  return nullptr;
+}
+
+int Cartridge::mediaCount() const {
+  return static_cast<int>(m_references.size());
+}
+
+std::unique_ptr<Media> Cartridge::splashScreen() {
+  return getMedia(m_splashScreenId);
+}
+std::unique_ptr<Media> Cartridge::smallIcon() { return getMedia(m_smallIconId); }
+std::unique_ptr<Media> Cartridge::luac() { return getMedia(0); }
+
+bool Cartridge::operator==(const Cartridge &other) const {
+  return m_cartridgeGuid == other.m_cartridgeGuid;
+}
+bool Cartridge::operator!=(const Cartridge &other) const {
+  return !(*this == other);
+}
+
+} // namespace cartridge

components/cartridge/src/lat_lng.cpp

@@ -0,0 +1,54 @@
+// MIT License
+// Copyright (c) 2026 by Peter Siegmund (mars3142)
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
+
+#include "cartridge/lat_lng.h"
+
+#include <cmath>
+#include <format>
+
+namespace cartridge {
+
+LatLng::LatLng(const double latitude, const double longitude)
+    : m_latitude(latitude), m_longitude(longitude) {}
+
+std::string LatLng::latitude() const { return _format(m_latitude, "NS"); }
+
+std::string LatLng::longitude() const { return _format(m_longitude, "EW"); }
+
+std::string LatLng::toString() const {
+  const std::string lat = latitude();
+  const std::string lon = longitude();
+  if (!lat.empty() && !lon.empty()) {
+    return lat + " " + lon;
+  }
+  return lat + lon;
+}
+
+std::string LatLng::_format(double value, const std::string &suffix) {
+  const bool isNegative = value < 0;
+  value = std::abs(value);
+  const int degrees = static_cast<int>(std::floor(value));
+  if (degrees == 360) {
+    return "";
+  }
+  const double minutes = (value - degrees) * 60.0;
+  return std::format("{} {}\u00B0 {:.3f}",
+                     isNegative ? suffix.substr(1, 1) : suffix.substr(0, 1),
+                     degrees, minutes);
+}
+} // namespace cartridge

components/cartridge/src/media.cpp

@@ -0,0 +1,89 @@
+// MIT License
+// Copyright (c) 2026 by Peter Siegmund (mars3142)
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
+
+#include "cartridge/media.h"
+
+#include <utility>
+#include <format>
+
+namespace cartridge {
+
+Media::Media(std::string objectType, const std::vector<uint8_t> &data)
+    : objectType(std::move(objectType)), data(data) {}
+
+std::unique_ptr<Media> Media::create(BinaryReader &reader, const int objectId,
+                                     const int address) {
+  try {
+    int objectType = 0;
+    reader.seek(address, SeekOrigin::Begin);
+    std::vector<uint8_t> data = (objectId == 0)
+        ? readMediaData(reader)
+        : (reader.getByte() != 0)
+            ? (objectType = reader.getLong(), readMediaData(reader))
+            : std::vector<uint8_t>{};
+
+    if (!data.empty()) {
+      return std::make_unique<Media>(getObjectTypeString(objectType), data);
+    }
+    return nullptr;
+  } catch ([[maybe_unused]] const std::exception &ex) {
+    return nullptr;
+  }
+}
+
+std::vector<uint8_t> Media::readMediaData(BinaryReader &reader) {
+  const int32_t length = reader.getLong();
+  std::vector<uint8_t> data(length);
+  for (int32_t i = 0; i < length; ++i) {
+    data[i] = reader.getByte();
+  }
+  return data;
+}
+
+std::string Media::getObjectTypeString(const int objectType) {
+  switch (objectType) {
+  case -1: return "deleted";
+  case 0:  return "luac";
+  case 1:  return "bmp";
+  case 2:  return "png";
+  case 3:  return "jpg";
+  case 4:  return "gif";
+  case 17: return "wav";
+  case 18: return "mp3";
+  case 19: return "fdl";
+  case 20: return "snd";
+  case 21: return "ogg";
+  case 33: return "swf";
+  case 49: return "txt";
+  default: return std::format("invalid ({})", objectType);
+  }
+}
+
+bool Media::operator==(const Media &other) const {
+  return objectType == other.objectType && data == other.data;
+}
+
+std::size_t Media::hash() const {
+  const std::size_t h1 = std::hash<std::string>{}(objectType);
+  std::size_t h2 = 0;
+  for (const auto b : data)
+    h2 ^= std::hash<uint8_t>{}(b) + 0x9e3779b9 + (h2 << 6) + (h2 >> 2);
+  return h1 ^ (h2 << 1);
+}
+
+} // namespace cartridge

components/cartridge/src/parser.cpp

@@ -0,0 +1,101 @@
+// MIT License
+// Copyright (c) 2026 by Peter Siegmund (mars3142)
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
+
+#include "cartridge/parser.h"
+#include "storage/storage.h"
+
+#include <array>
+#include <algorithm>
+#include <filesystem>
+#include <format>
+#include <iostream>
+#include <print>
+#include <ranges>
+
+namespace cartridge {
+
+std::unique_ptr<Cartridge> parseData(const std::vector<uint8_t> &bytes) {
+  try {
+    constexpr std::array<uint8_t, 7> header = {0x02, 0x0a, 0x43, 0x41,
+                                               0x52, 0x54, 0x00};
+    BinaryReader reader(bytes, Endian::Little);
+
+    if (!std::ranges::all_of(header, [&reader](const uint8_t expected) {
+      return reader.getByte() == expected;
+    })) {
+      return nullptr;
+    }
+
+    return Cartridge::create(reader);
+  } catch (...) {
+    return nullptr;
+  }
+}
+
+std::unique_ptr<Cartridge> parseFile(const std::string &filePath) {
+  storage::Storage storage;
+  auto result = storage.readFile(filePath);
+  if (!result) {
+    std::println(std::cerr, "Fehler beim Lesen der Datei: {}", filePath);
+    return nullptr;
+  }
+  return parseData(*result);
+}
+
+std::unique_ptr<Cartridge> parseCartridge() {
+  auto cartridge = parseFile("/Volumes/Coding/git.mars3142.dev/mars3142/"
+                             "wx_wherigo/cartridges/the_ombos_idol_-_c.gwc");
+  if (!cartridge) {
+    std::println(std::cerr, "Cartridge konnte nicht geladen werden.");
+    return nullptr;
+  }
+
+  const int count = cartridge->mediaCount();
+  const std::filesystem::path outDir =
+      "/Volumes/Coding/git.mars3142.dev/mars3142/wx_wherigo/cartridges";
+  storage::Storage storage;
+
+  for (const int i : std::views::iota(0, count)) {
+    auto media = cartridge->getMedia(i);
+    if (!media) {
+      std::println(std::cerr, "Media-Objekt an Index {} ist nullptr.", i);
+      continue;
+    }
+
+    const auto &data = media->getData();
+    if (data.empty()) {
+      std::println(std::cerr, "Media-Daten an Index {} sind leer.", i);
+      continue;
+    }
+
+    std::string ext = media->getObjectType();
+    if (ext.empty()) {
+      std::println(std::cerr, "Media-Extension an Index {} ist leer.", i);
+      ext = "bin";
+    }
+
+    const std::filesystem::path outFile = outDir / std::format("file{}.{}", i, ext);
+
+    if (auto writeResult = storage.writeFile(outFile.string(), data); !writeResult) {
+      std::println(std::cerr, "Fehler beim Schreiben der Datei: {}", outFile.string());
+    }
+  }
+  return cartridge;
+}
+
+} // namespace cartridge

components/cartridge/version.h.in

@@ -0,0 +1,7 @@
+#pragma once
+
+#define CARTRIDGE_VERSION_MAJOR @CARTRIDGE_VERSION_MAJOR@
+#define CARTRIDGE_VERSION_MINOR @CARTRIDGE_VERSION_MINOR@
+#define CARTRIDGE_VERSION_PATCH @CARTRIDGE_VERSION_PATCH@
+#define CARTRIDGE_VERSION "@CARTRIDGE_VERSION@"
+

components/storage/CMakeLists.txt

@@ -0,0 +1,26 @@
+set(STORAGE_VERSION_MAJOR 1)
+set(STORAGE_VERSION_MINOR 0)
+set(STORAGE_VERSION_PATCH 0)
+set(STORAGE_VERSION "${STORAGE_VERSION_MAJOR}.${STORAGE_VERSION_MINOR}.${STORAGE_VERSION_PATCH}")
+
+configure_file(
+    ${CMAKE_CURRENT_SOURCE_DIR}/version.h.in
+    ${CMAKE_CURRENT_BINARY_DIR}/include/storage/version.h
+    @ONLY
+)
+
+set(STORAGE_SRC
+        src/storage.cpp
+)
+
+add_library(storage SHARED ${STORAGE_SRC})
+set_target_properties(storage PROPERTIES
+        VERSION ${STORAGE_VERSION}
+        SOVERSION ${STORAGE_VERSION_MAJOR}
+)
+
+target_include_directories(storage
+        PUBLIC
+        ${CMAKE_CURRENT_SOURCE_DIR}/include
+        ${CMAKE_CURRENT_BINARY_DIR}/include
+)

components/storage/include/storage/storage.h

@@ -0,0 +1,50 @@
+// MIT License
+// Copyright (c) 2026 by Peter Siegmund (mars3142)
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
+
+#pragma once
+
+#include "storage/storage_error.h"
+
+#include <expected>
+#include <string>
+#include <vector>
+
+namespace storage {
+
+class Storage {
+public:
+  /**
+   * Liest eine Datei von einem Pfad.
+   * @param path Der Dateipfad.
+   * @return Ein expected mit den Dateidaten oder einem StorageError.
+   */
+  [[nodiscard]] std::expected<std::vector<uint8_t>, StorageError> readFile(
+      const std::string &path) const;
+
+  /**
+   * Schreibt Daten in eine Datei.
+   * @param path Der Dateipfad.
+   * @param data Die zu schreibenden Daten.
+   * @return Ein expected<void> oder einem StorageError.
+   */
+  [[nodiscard]] std::expected<void, StorageError> writeFile(
+      const std::string &path,
+      const std::vector<uint8_t> &data) const;
+};
+
+} // namespace storage

components/storage/include/storage/storage_error.h

@@ -0,0 +1,29 @@
+// MIT License
+// Copyright (c) 2026 by Peter Siegmund (mars3142)
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
+
+#pragma once
+
+namespace storage {
+
+enum class StorageError {
+  FileNotFound,
+  ReadError,
+  WriteError,
+};
+
+} // namespace storage

components/storage/src/storage.cpp

@@ -0,0 +1,59 @@
+// MIT License
+// Copyright (c) 2026 by Peter Siegmund (mars3142)
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
+
+#include "storage/storage.h"
+
+#include <fstream>
+
+namespace storage {
+
+std::expected<std::vector<uint8_t>, StorageError> Storage::readFile(
+    const std::string &path) const {
+  std::ifstream file(path, std::ios::binary | std::ios::ate);
+  if (!file) {
+    return std::unexpected(StorageError::FileNotFound);
+  }
+
+  const std::streamsize size = file.tellg();
+  if (size < 0) {
+    return std::unexpected(StorageError::ReadError);
+  }
+  file.seekg(0, std::ios::beg);
+
+  std::vector<uint8_t> data(static_cast<size_t>(size));
+  if (!file.read(reinterpret_cast<char *>(data.data()), size)) {
+    return std::unexpected(StorageError::ReadError);
+  }
+  return data;
+}
+
+std::expected<void, StorageError> Storage::writeFile(
+    const std::string &path,
+    const std::vector<uint8_t> &data) const {
+  std::ofstream file(path, std::ios::binary);
+  if (!file) {
+    return std::unexpected(StorageError::WriteError);
+  }
+  file.write(reinterpret_cast<const char *>(data.data()), data.size());
+  if (!file.good()) {
+    return std::unexpected(StorageError::WriteError);
+  }
+  return {};
+}
+
+} // namespace storage

components/storage/version.h.in

@@ -0,0 +1,7 @@
+#pragma once
+
+#define STORAGE_VERSION_MAJOR @STORAGE_VERSION_MAJOR@
+#define STORAGE_VERSION_MINOR @STORAGE_VERSION_MINOR@
+#define STORAGE_VERSION_PATCH @STORAGE_VERSION_PATCH@
+#define STORAGE_VERSION "@STORAGE_VERSION@"
+