Add parser support for Tiled hex colors as ui.Color (#52)

Adding direct support for parsing color hex strings as dart.ui.Color objects, which is the primary type the interoperates with Dart rendering libraries and most Canvas methods use.

Also, should eventually replace _parseTiledColor in flame_tiled RenderableTileMap.

Author: kurtome

CHANGELOG.md

@@ -1,3 +1,8 @@
+## [Next]
+* Add parser support for Tiled hex colors as `ui.Color`
+* BREAKING CHANGE: re-named string color fields to `colorHex` such as `layer.tintColorHex` and 
+  added a new `color` field paired with each `colorHex` field of type `ui.Color`.
+
 ## 0.8.4
 * Adding "class" attribute for Tiled 1.9's Unified Custom Types:
     * On `Tile` accessible as `class_` or `type`, backwards compatible with "type" property 

lib/src/layer.dart

@@ -75,7 +75,13 @@ abstract class Layer {
 
   /// Hex-formatted tint color (#RRGGBB or #AARRGGBB) that is multiplied with
   /// any graphics drawn by this layer or any child layers (optional).
-  String? tintColor;
+  String? tintColorHex;
+
+  /// [Color] that is multiplied with any graphics drawn by this layer or any
+  /// child layers (optional).
+  ///
+  /// Parsed from [tintColorHex], will be null if parsing fails for any reason.
+  Color? tintColor;
 
   /// The opacity of the layer as a value from 0 to 1. Defaults to 1.
   double opacity;
@@ -99,6 +105,7 @@ abstract class Layer {
     this.parallaxY = 1,
     this.startX,
     this.startY,
+    this.tintColorHex,
     this.tintColor,
     this.opacity = 1,
     this.visible = true,
@@ -122,7 +129,8 @@ abstract class Layer {
     final parallaxY = parser.getDouble('parallaxy', defaults: 1);
     final startX = parser.getIntOrNull('startx');
     final startY = parser.getIntOrNull('starty');
-    final tintColor = parser.getStringOrNull('tintcolor');
+    final tintColorHex = parser.getStringOrNull('tintcolor');
+    final tintColor = parser.getColorOrNull('tintcolor');
     final opacity = parser.getDouble('opacity', defaults: 1);
     final visible = parser.getBool('visible', defaults: true);
     final properties = parser.getProperties();
@@ -159,6 +167,7 @@ abstract class Layer {
           parallaxY: parallaxY,
           startX: startX,
           startY: startY,
+          tintColorHex: tintColorHex,
           tintColor: tintColor,
           opacity: opacity,
           visible: visible,
@@ -176,7 +185,10 @@ abstract class Layer {
           'draworder',
           defaults: DrawOrder.topDown,
         );
-        final color = parser.getString('color', defaults: '#a0a0a4');
+        final colorHex =
+            parser.getString('color', defaults: ObjectGroup.defaultColorHex);
+        final color =
+            parser.getColor('color', defaults: ObjectGroup.defaultColor);
         final objects = parser.getChildrenAs('object', TiledObject.parse);
         layer = ObjectGroup(
           id: id,
@@ -190,17 +202,20 @@ abstract class Layer {
           parallaxY: parallaxY,
           startX: startX,
           startY: startY,
+          tintColorHex: tintColorHex,
           tintColor: tintColor,
           opacity: opacity,
           visible: visible,
           properties: properties,
           drawOrder: drawOrder,
           objects: objects,
+          colorHex: colorHex,
           color: color,
         );
         break;
       case LayerType.imageLayer:
-        final transparentColor = parser.getStringOrNull('transparentcolor');
+        final transparentColorHex = parser.getStringOrNull('transparentcolor');
+        final transparentColor = parser.getColorOrNull('transparentcolor');
         final image = parser.getSingleChildAs('image', TiledImage.parse);
         final repeatX = parser.getBool('repeatx', defaults: false);
         final repeatY = parser.getBool('repeaty', defaults: false);
@@ -218,11 +233,13 @@ abstract class Layer {
           repeatY: repeatY,
           startX: startX,
           startY: startY,
+          tintColorHex: tintColorHex,
           tintColor: tintColor,
           opacity: opacity,
           visible: visible,
           properties: properties,
           image: image,
+          transparentColorHex: transparentColorHex,
           transparentColor: transparentColor,
         );
         break;
@@ -240,6 +257,7 @@ abstract class Layer {
           parallaxY: parallaxY,
           startX: startX,
           startY: startY,
+          tintColorHex: tintColorHex,
           tintColor: tintColor,
           opacity: opacity,
           visible: visible,
@@ -374,7 +392,8 @@ class TileLayer extends Layer {
     double parallaxY = 1,
     int? startX,
     int? startY,
-    String? tintColor,
+    String? tintColorHex,
+    Color? tintColor,
     double opacity = 1,
     bool visible = true,
     List<Property> properties = const [],
@@ -398,11 +417,13 @@ class TileLayer extends Layer {
           parallaxY: parallaxY,
           startX: startX,
           startY: startY,
+          tintColorHex: tintColorHex,
           tintColor: tintColor,
           opacity: opacity,
           visible: visible,
           properties: properties,
         );
+
   static List<List<Gid>>? maybeGenerate(
     List<int>? data,
     int width,
@@ -416,15 +437,25 @@ class TileLayer extends Layer {
 }
 
 class ObjectGroup extends Layer {
+  static const defaultColor = Color.fromARGB(255, 160, 160, 164);
+  static const defaultColorHex = '%a0a0a4';
+
   /// topdown (default) or index (indexOrder).
   DrawOrder drawOrder;
 
   /// List of [TiledObject].
   List<TiledObject> objects;
 
-  /// The color used to display the objects in this group.
+  /// Hex-formatted color (#RRGGBB or #AARRGGBB) used to display the objects in
+  /// this group. (defaults to gray (“#a0a0a4”))
+  String colorHex;
+
+  /// [Color] used to display the objects in this group.
   /// (defaults to gray (“#a0a0a4”))
-  String color;
+  ///
+  /// Parsed from [colorHex], will be fallback to [defaultColor] if parsing
+  /// fails for any reason.
+  Color color;
 
   ObjectGroup({
     int? id,
@@ -438,13 +469,15 @@ class ObjectGroup extends Layer {
     double parallaxY = 1,
     int? startX,
     int? startY,
-    String? tintColor,
+    String? tintColorHex,
+    Color? tintColor,
     double opacity = 1,
     bool visible = true,
     List<Property> properties = const [],
     this.drawOrder = DrawOrder.topDown,
     required this.objects,
-    this.color = '#a0a0a4',
+    this.colorHex = defaultColorHex,
+    this.color = defaultColor,
   }) : super(
           id: id,
           name: name,
@@ -458,6 +491,7 @@ class ObjectGroup extends Layer {
           parallaxY: parallaxY,
           startX: startX,
           startY: startY,
+          tintColorHex: tintColorHex,
           tintColor: tintColor,
           opacity: opacity,
           visible: visible,
@@ -469,8 +503,15 @@ class ImageLayer extends Layer {
   /// Image used by this layer.
   TiledImage image;
 
-  /// Hex-formatted color (#RRGGBB) (optional).
-  String? transparentColor;
+  /// Hex-formatted color (#RRGGBB or #AARRGGBB) to be rendered as transparent
+  /// (optional).
+  String? transparentColorHex;
+
+  /// [Color] to be rendered as transparent (optional).
+  ///
+  /// Parsed from [transparentColorHex], will be null if parsing fails for any
+  /// reason.
+  Color? transparentColor;
 
   /// Whether or not to repeat the image on the X-axis
   bool repeatX;
@@ -490,13 +531,15 @@ class ImageLayer extends Layer {
     double parallaxY = 1,
     int? startX,
     int? startY,
-    String? tintColor,
+    String? tintColorHex,
+    Color? tintColor,
     double opacity = 1,
     bool visible = true,
     List<Property> properties = const [],
     required this.image,
     required this.repeatX,
     required this.repeatY,
+    this.transparentColorHex,
     this.transparentColor,
   }) : super(
           id: id,
@@ -511,6 +554,7 @@ class ImageLayer extends Layer {
           parallaxY: parallaxY,
           startX: startX,
           startY: startY,
+          tintColorHex: tintColorHex,
           tintColor: tintColor,
           opacity: opacity,
           visible: visible,
@@ -534,7 +578,8 @@ class Group extends Layer {
     double parallaxY = 1,
     int? startX,
     int? startY,
-    String? tintColor,
+    String? tintColorHex,
+    Color? tintColor,
     double opacity = 1,
     bool visible = true,
     List<Property> properties = const [],
@@ -552,6 +597,7 @@ class Group extends Layer {
           parallaxY: parallaxY,
           startX: startX,
           startY: startY,
+          tintColorHex: tintColorHex,
           tintColor: tintColor,
           opacity: opacity,
           visible: visible,

lib/src/parser.dart

@@ -197,6 +197,35 @@ abstract class Parser {
     return result;
   }
 
+  Color? getColorOrNull(String name, {Color? defaults}) {
+    final tiledColor = getStringOrNull(name);
+
+    // Tiled colors are stored as either ARGB or RGB hex values, so we can
+    // parse them as hex numbers with a little coercing.
+    int? colorValue;
+    if (tiledColor?.length == 7) {
+      // parse '#rrbbgg'  as hex '0xaarrggbb' with the alpha channel on full
+      colorValue = int.tryParse(tiledColor!.replaceFirst('#', '0xff'));
+    } else if (tiledColor?.length == 9) {
+      // parse '#aarrbbgg'  as hex '0xaarrggbb'
+      colorValue = int.tryParse(tiledColor!.replaceFirst('#', '0x'));
+    }
+
+    if (colorValue != null) {
+      return Color(colorValue);
+    } else {
+      return defaults;
+    }
+  }
+
+  Color getColor(String name, {Color? defaults}) {
+    final result = getColorOrNull(name, defaults: defaults);
+    if (result == null) {
+      throw ParsingException(name, null, 'Missing required color field');
+    }
+    return result;
+  }
+
   T? getRawEnumOrNull<T>(
     List<T> values,
     String Function(T) namer,

lib/src/tiled_map.dart

@@ -69,7 +69,17 @@ class TiledMap {
   List<Tileset> tilesets;
   List<Layer> layers;
 
-  String? backgroundColor;
+  /// Hex-formatted color (#RRGGBB or #AARRGGBB) to be rendered as a solid color
+  /// behind all other layers (optional).
+  String? backgroundColorHex;
+
+  /// [Color] to be rendered as a solid color behind all other layers
+  /// (optional).
+  ///
+  /// Parsed from [backgroundColorHex], will be null if parsing fails for any
+  /// reason.
+  Color? backgroundColor;
+
   int compressionLevel;
 
   int? nextLayerId;
@@ -96,6 +106,7 @@ class TiledMap {
     required this.tileHeight,
     this.tilesets = const [],
     this.layers = const [],
+    this.backgroundColorHex,
     this.backgroundColor,
     this.compressionLevel = -1,
     this.hexSideLength,
@@ -224,7 +235,8 @@ class TiledMap {
   }
 
   static TiledMap parse(Parser parser, {List<TsxProvider>? tsxList}) {
-    final backgroundColor = parser.getStringOrNull('backgroundcolor');
+    final backgroundColorHex = parser.getStringOrNull('backgroundcolor');
+    final backgroundColor = parser.getColorOrNull('backgroundcolor');
     final compressionLevel = parser.getInt('compressionlevel', defaults: -1);
     final height = parser.getInt('height');
     final hexSideLength = parser.getIntOrNull('hexsidelength');
@@ -280,6 +292,7 @@ class TiledMap {
       tileHeight: tileHeight,
       tilesets: tilesets,
       layers: layers,
+      backgroundColorHex: backgroundColorHex,
       backgroundColor: backgroundColor,
       compressionLevel: compressionLevel,
       hexSideLength: hexSideLength,

lib/tiled.dart

@@ -3,6 +3,7 @@ library tiled;
 import 'dart:convert';
 import 'dart:math' show Rectangle;
 import 'dart:typed_data';
+import 'dart:ui';
 
 import 'package:archive/archive.dart';
 import 'package:meta/meta.dart';

test/fixtures/test.tmx

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<map version="1.2" tiledversion="1.2.1" orientation="orthogonal" renderorder="right-down" width="10" height="10" tilewidth="32" tileheight="32" infinite="0" nextlayerid="2" nextobjectid="1">
+<map version="1.2" tiledversion="1.2.1" orientation="orthogonal" renderorder="right-down" width="10" height="10" tilewidth="32" tileheight="32" infinite="0" nextlayerid="2" nextobjectid="1" backgroundcolor="#ccddaaff">
  <tileset firstgid="1" name="basketball" tilewidth="32" tileheight="32" tilecount="2" columns="1">
   <properties>
    <property name="test_property" value="test_value"/>
@@ -16,7 +16,7 @@
    </properties>
   </tile>
  </tileset>
- <layer id="1" name="Tile Layer 1" width="10" height="10" class="layer1Class">
+ <layer id="1" name="Tile Layer 1" width="10" height="10" class="layer1Class" tintcolor="#ffaabb">
   <data encoding="base64" compression="zlib">
    eJxjZCAeMI6qpblaAAl0AAs=
   </data>

test/layer_test.dart

@@ -1,5 +1,6 @@
 import 'dart:async';
 import 'dart:io';
+import 'dart:ui';
 
 import 'package:test/test.dart';
 import 'package:tiled/tiled.dart';
@@ -70,5 +71,13 @@ void main() {
         expect(row.length, equals(10));
       });
     });
+
+    test('parsed colors', () {
+      expect(layer.tintColorHex, equals('#ffaabb'));
+      expect(
+        layer.tintColor,
+        equals(Color(int.parse('0xffffaabb'))),
+      );
+    });
   });
 }

test/object_group_test.dart

@@ -1,4 +1,5 @@
 import 'dart:io';
+import 'dart:ui';
 
 import 'package:test/test.dart';
 import 'package:tiled/tiled.dart';
@@ -27,7 +28,11 @@ void main() {
     });
 
     test('sets color', () {
-      expect(objectGroup.color, equals('#555500'));
+      expect(objectGroup.colorHex, equals('#555500'));
+      expect(
+        objectGroup.color,
+        equals(Color(int.parse('0xff555500'))),
+      );
     });
 
     test('sets opacity', () {