AGS 4: Script API: implement FaceDirectionRatio

[ivan-mogilko]

Resolves #2243

This implements new property called FaceDirectionRatio for Game, Room, WalkableArea and Character. This property affects selection of directional loop while Character moves and turns.

/// Gets/sets the default y/x ratio of character's facing directions, determining directional loop selection for all Characters in game.
static attribute float Game.FaceDirectionRatio;

/// Gets/sets the optional y/x ratio of character's facing directions, determining directional loop selection for each Character in the current room.
static attribute float Room.FaceDirectionRatio;

/// Gets/sets the optional y/x ratio of character's facing directions, determining directional loop selection for each Character while on this area.
static attribute float FaceDirectionRatio;

/// Gets/sets the optional y/x ratio of character's facing directions, determining directional loop selection while Character moves and turns.
attribute float Character.FaceDirectionRatio;

Ratio's implementation is loosely based on the experimental commit in @AlanDrake 's custom "Draconian" engine. The meaning of ratio is (Y / X) relation. Default value is 1.0, where loop selection strictly corresponds to movement and facing dir. Values >1.0 mean that Y axis has more "weight", and vertical loops are chosen for the wider range of angles. Values <1.0 mean that X axis has more "weight", and horizontal loops are chosen for the wider range of angles.

This may be also illustrated with this pic:

The properties are checked in following order:

1. Individual Character.FaceDirectionRatio, if it's > 0;
2. WalkableArea.FaceDirectionRatio, if it's > 0;
3. Room.FaceDirectionRatio, if it's > 0;
4. If none of above, then Game.FaceDirectionRatio

---

Potential TODOs:

• Add respective properties in General Settings and Room properties in the Editor. Idk if Characters need an individual design-time property for this, I suppose character's property serves rather as an override in some narrow use cases.
• Add property for Walkable Areas in the Editor, in which case it will be checked after Character's but before Room's.
• Float properties are parsed depending on Culture, which should not be happening. To clarify: on some systems it will require "2.5" (with a dot) and on others "2,5" (with a comma). Need to figure out how to enforce InvariantCulture in the PropertyGrid.
• Add script property for Walkable Areas, but I don't want to do this right away here, as WAs don't have their respective struct. I'd rather wait until their api is replaced with OO-style api first (opened pr for this AGS 4: Script API: convert Walk-areas and Walkbehinds API to OO-style #2307).
• Save properties that may be changed at runtime.

[ ] Optimize direction ration calculation by caching few things in character class.

---

Test game, made with assets by user who requested this feature recently:
IsoBikeDemo.zip

[ivan-mogilko]

Added design-time properties for Game (in General Settings), Room and Walkable area.

Two problems:

1. I don't know how to write description brief and clear enough for regular users to understand :).
2. Float properties are parsed depending on Culture, which should not be happening. To clarify: on some systems it will require "2.5" (with a dot) and on others "2,5" (with a comma). Need to figure out how to enforce InvariantCulture in the PropertyGrid.

[ivan-mogilko]

After #2307 added a script property to WalkableArea struct too.

[ivan-mogilko]

I just realized, that the Editor already has a workaround for floats implemented during serialization, a very long time ago:

ags/Editor/AGS.Types/SerializeUtils.cs

Lines 143 to 152 in b148832

	// We must use InvariantCulture for floats and doubles, because their
	// format depends on local system settings used when the project was saved
	else if (prop.PropertyType == typeof(float))
	{
	writer.WriteElementString(prop.Name, ((float)prop.GetValue(obj, null)).ToString(CultureInfo.InvariantCulture));
	}
	else if (prop.PropertyType == typeof(double))
	{
	writer.WriteElementString(prop.Name, ((double)prop.GetValue(obj, null)).ToString(CultureInfo.InvariantCulture));
	}

ags/Editor/AGS.Types/SerializeUtils.cs

Lines 241 to 250 in b148832

	// We must use InvariantCulture for floats and doubles, because their
	// format depends on local system settings used when the project was saved
	else if (prop.PropertyType == typeof(float))
	{
	prop.SetValue(obj, Single.Parse(elementValue, CultureInfo.InvariantCulture), null);
	}
	else if (prop.PropertyType == typeof(double))
	{
	prop.SetValue(obj, Double.Parse(elementValue, CultureInfo.InvariantCulture), null);
	}

So, these values will save and load using InvariantCulture at least. The only issue remaining is how they are displayed in the property grid, but this may be a lesser priority.

(I was not able to find how to apply the "culture" to a property grid control or particular fields, except for writing a custom typeconverter, which I don't like...

[ivan-mogilko]

Following a proposal by @messengerbag, allowed negative ratios, which basically swap up/down loops. This maybe will work for "going downhill" kind of effects in game.

[ivan-mogilko]

Added a test game, with assets made by user who requested this feature recently:
https://github.com/adventuregamestudio/ags/files/14254038/test--ags4-directionratio.zip

[ivan-mogilko]

In regards to this subtask:

Optimize direction ration calculation by caching few things in character class.

I decided to leave this out, and only have couple TODOs in code. I found that with the current order of character update checking "area" under the feet will be called about same amount of times anyway; and caching things is often bug prone in AGS, as character state (like position) may be changed in a random script callback. So i'd rather leave this kind of improvement for later.

[ivan-mogilko]

Updated test game, now made by blaholtzen, with 2 characters featuring different face ratios:
https://github.com/adventuregamestudio/ags/files/14316758/IsoBikeDemo.zip

[ericoporto]

That demo game is super cute. It appears it works. I noticed no new property is added for the character in their properties in the Editor, is that intended? (I ask because of the comment above)

[ivan-mogilko]

I added this setting to GeneralSettings, Room and Walkable Area, but not the Character, because it seems that the common case for using the character's individual property is when scripting custom behavior.