TKProperties Class Reference

Inherits from NSObject
Declared in TKProperties.h

Overview

Represents properties (key-value entries). Much like a mutable dictionary, but only allows certain data types as values and assumes all keys to be strings.

Note: The storage of arbitrary object types is disallowed as they can not be serialized to the TMX format.

Property types

You can store the following types:

  • bool
  • int32_t aka int (can be cast to unsigned int32_t)
  • float
  • std::string (as shared_ptr)

All values are internally stored as float, this limits integers to a 31-bit range. That’s still plenty.

Likewise, if you use floating point numbers, know that float type has about 6-7 precise digits, the rest is “approximate”. For instance, given the string “0.123456789” the resulting float value is 0.123456791 - precise to 7 digits with the remaining fractional part approximated.

It is assumed that game developers do not need to edit double precision floating point values in Tiled. Lower memory usage seems by far the greater concern.

Property type conversion

All property values in Tiled (and the TMX format) are encoded as string. This makes converting them back to their intended types a tad difficult. So here are the rules:

  • If the value string only contains digits, the value type is int.
  • If the value string only contains digits and exactly one dot, the value type is float.
  • If the value string equals (case insensitive) the strings “true”, “YES”, “false” or “NO” the value type is bool.
  • If all of the above conditions fail, the value string is taken literally as a string.

Since all values are stored as float and cast as needed by the getter, it doesn’t matter whether a presumed float value of 123 is initially assumed to be an integer. The same goes for bool values 0 and 1 which will be assumed to be int, but will be properly cast to bool by the property getter (any non-zero value is assumed to be true).

Classes with Properties

These tilemap classes have properties:

Counting Properties

  count

The total number of unique property keys in the properties dictionary.

@property (readonly) NSUInteger count

Declared In

TKProperties.h

Accessing Values

– boolForKey:

Obtains a BOOL value for the given key.

- (BOOL)boolForKey:(nonnull NSString *)key

Parameters

key

The unique key for which to get the value.

Return Value

The BOOL value for the given key. Defaults to NO.

Declared In

TKProperties.h

– boolForKey:default:

Obtains a BOOL value for the given key.

- (BOOL)boolForKey:(nonnull NSString *)key default:(BOOL)value

Parameters

key

The unique key for which to get the value.

value

This value is returned if the key doesn’t exist.

Return Value

The BOOL value for the given key. Defaults to NO.

Declared In

TKProperties.h

– floatForKey:

Obtains a float value for the given key.

- (float)floatForKey:(nonnull NSString *)key

Parameters

key

The unique key for which to get the value.

Return Value

The float value for the given key. Defaults to 0.0f.

Declared In

TKProperties.h

– floatForKey:default:

Obtains a float value for the given key.

- (float)floatForKey:(nonnull NSString *)key default:(float)value

Parameters

key

The unique key for which to get the value.

value

This value is returned if the key doesn’t exist.

Return Value

The float value for the given key. Defaults to 0.0f.

Declared In

TKProperties.h

– intForKey:

Obtains a int32_t value for the given key.

- (int32_t)intForKey:(nonnull NSString *)key

Parameters

key

The unique key for which to get the value.

Return Value

The int32_t value for the given key. Defaults to 0.

Declared In

TKProperties.h

– intForKey:default:

Obtains a int32_t value for the given key.

- (int32_t)intForKey:(nonnull NSString *)key default:(int32_t)value

Parameters

key

The unique key for which to get the value.

value

This value is returned if the key doesn’t exist.

Return Value

The int32_t value for the given key. Defaults to 0.

Declared In

TKProperties.h

– unsignedIntForKey:

Obtains a uint32_t value for the given key.

- (uint32_t)unsignedIntForKey:(nonnull NSString *)key

Parameters

key

The unique key for which to get the value.

Return Value

The uint32_t value for the given key. Defaults to 0.

Declared In

TKProperties.h

– unsignedIntForKey:default:

Obtains a uint32_t value for the given key.

- (uint32_t)unsignedIntForKey:(nonnull NSString *)key default:(uint32_t)value

Parameters

key

The unique key for which to get the value.

value

This value is returned if the key doesn’t exist.

Return Value

The uint32_t value for the given key. Defaults to 0.

Declared In

TKProperties.h

– stringForKey:

Obtains a NSString object for the given key.

- (nullable NSString *)stringForKey:(nonnull NSString *)key

Parameters

key

The unique key for which to get the value.

Return Value

The string for the given key. Returns nil if there’s no string for the given key.

Declared In

TKProperties.h

– stringForKey:default:

Obtains a NSString object for the given key.

- (nonnull NSString *)stringForKey:(nonnull NSString *)key default:(nonnull NSString *)value

Parameters

key

The unique key for which to get the value.

value

This value is returned if the key doesn’t exist.

Return Value

The string for the given key. Returns nil if there’s no string for the given key.

Declared In

TKProperties.h

– numberForKey:

Obtains a NSNumber object for the given key.

- (nullable NSNumber *)numberForKey:(nonnull NSString *)key

Parameters

key

The unique key for which to get the value.

Return Value

The number for the given key. Returns nil if there’s no number for the given key.

Declared In

TKProperties.h

– numberForKey:default:

Obtains a NSNumber object for the given key.

- (nonnull NSNumber *)numberForKey:(nonnull NSString *)key default:(nonnull NSNumber *)value

Parameters

key

The unique key for which to get the value.

value

This value is returned if the key doesn’t exist.

Return Value

The number for the given key. Returns nil if there’s no number for the given key.

Declared In

TKProperties.h

Setting Values

– setBool:forKey:

Sets a BOOL value for the given key. Overwrites any existing value of the same key.

- (void)setBool:(BOOL)value forKey:(nonnull NSString *)key

Parameters

value

The value to set.

key

The unique key for which to set the value.

Declared In

TKProperties.h

– setFloat:forKey:

Sets a float value for the given key. Overwrites any existing value of the same key.

- (void)setFloat:(float)value forKey:(nonnull NSString *)key

Parameters

value

The value to set.

key

The unique key for which to set the value.

Declared In

TKProperties.h

– setInt:forKey:

Sets a int32_t value for the given key. Overwrites any existing value of the same key.

- (void)setInt:(int32_t)value forKey:(nonnull NSString *)key

Parameters

value

The value to set.

key

The unique key for which to set the value.

Declared In

TKProperties.h

– setUnsignedInt:forKey:

Sets a uint32_t value for the given key. Overwrites any existing value of the same key.

- (void)setUnsignedInt:(uint32_t)value forKey:(nonnull NSString *)key

Parameters

value

The value to set.

key

The unique key for which to set the value.

Declared In

TKProperties.h

– setString:forKey:

Sets a NSString object for the given key. Replaces any existing string of the same key.

- (void)setString:(nonnull NSString *)string forKey:(nonnull NSString *)key

Parameters

string

The string to set.

key

The unique key for which to set the value.

Declared In

TKProperties.h

– setNumber:forKey:

Sets a NSNumber object for the given key. Replaces any existing number of the same key.

- (void)setNumber:(nonnull NSNumber *)number forKey:(nonnull NSString *)key

Parameters

number

The number to set.

key

The unique key for which to set the value.

Declared In

TKProperties.h

Removing Values

– removeValueforKey:

Removes the value (any type) for the given key. Does nothing if the key doesn’t exist.

- (void)removeValueforKey:(nonnull NSString *)key

Parameters

key

The unique key to remove.

Declared In

TKProperties.h

Enumerating Properties

– enumerateKeysAndObjectsUsingBlock:

Applies a given block object to the entries of the properties dictionary.

- (void)enumerateKeysAndObjectsUsingBlock:(nullable void ( ^ ) ( NSString *__nonnull key , id __nonnull value , BOOL *__nullable stop ))block

Parameters

block

The block to execute for each property value.

Discussion

Block signature:

void (^)(NSString* key, id value, BOOL* stop);

The key will be a NSString while value can be either NSNumber or NSString*.

Declared In

TKProperties.h

– enumerateKeysAndObjectsWithOptions:usingBlock:

Applies a given block object to the entries of the properties dictionary using NSEnumerationOptions.

- (void)enumerateKeysAndObjectsWithOptions:(NSEnumerationOptions)options usingBlock:(nullable void ( ^ ) ( NSString *__nonnull key , id __nonnull value , BOOL *__nullable stop ))block

Parameters

options

Optional NSEnumerationOptions.

block

The block to execute for each property value.

Discussion

Block signature:

void (^)(NSString* key, id value, BOOL* stop);

The key will be a NSString while value can be either NSNumber or NSString*.

Declared In

TKProperties.h

Assigning Properties to Objects

– assignToObject:

Tries to assign properties with the prefix self. to the object, using KVC (key-value coding).

- (void)assignToObject:(nonnull id)object

Parameters

object

The object to which to assign the property’s values.

Discussion

The value type should match the property’s type. Though the value may be converted in the process where type conversion is possible, ie from int to float.

As in KVC, you can use a “key path”, for instance “self.bodySprite.anchorPoint” to relay the assignment to a child object, in this case to the anchorPoint property of the bodySprite object.

You may want to override the object class' setValue:forKey:, setValue:forKeyPath: and/or setValue:forUndefinedKey: methods in order to further process (failing) property assignments, for instance by forwarding the assignment to multiple child objects or applying a necessary decryption algorithm or performing a “string to ” conversion.

Declared In

TKProperties.h

– assignToObject:prefix:

Tries to assign properties with the prefix to the object, using KVC (key-value coding). Use the prefix to avoid ambiguity or possible crashes when you need to assign the same properties to different objects, for instance if you have different sets of properties for the TKTileLayer and TKTileLayerNode.

- (void)assignToObject:(nonnull id)object prefix:(nonnull NSString *)prefix

Parameters

object

The object to which to assign the property’s values.

prefix

Only properties whose key matches this prefix will be assigned to the object. Use an empty string to assign properties without using a prefix.

Discussion

The value type should match the property’s type. Though the value may be converted in the process where type conversion is possible, ie from int to float.

As in KVC, you can use a “key path”, for instance “self.bodySprite.anchorPoint” to relay the assignment to a child object, in this case to the anchorPoint property of the bodySprite object.

You may want to override the object class' setValue:forKey:, setValue:forKeyPath: and/or setValue:forUndefinedKey: methods in order to further process (failing) property assignments, for instance by forwarding the assignment to multiple child objects or applying a necessary decryption algorithm or performing a “string to ” conversion.

Declared In

TKProperties.h