[BUG] Character.ChangeRoomAutoPosition is broken

[Snarky]

See thread here.

The documentation for this method states:

Code: ags

Character.ChangeRoomAutoPosition(int room_number, optional int newPosition)

Changes the room that the character is in, and positions him along one of the room edges.

This command simulates the behavior of the old "Go to room" interaction command from AGS 2.72 and previous versions. If newPosition is not specified or is 0, the character will be placed on the opposite side of the new room, if he is within 10 pixels of a room edge in the current room.

Alternatively, you can specify the position where he will get placed in the new room. newPosition can be 1000 for the left edge, 2000 for the right edge, 3000 for the bottom edge and 4000 for the top edge. Then, add on the offset within that edge where you want to place the character, in normal room co-ordinates.

(1) It should be clear from this description that the function cannot work correctly in any game with a room width or height greater than 1000 (because the edge encoding will overflow).

(2) The documentation also leaves undefined how the character will be positioned if it is not within 10 pixels from a room edge.

(3) Khris reports that the current behavior of the function is buggy/not according to spec:

ChangeRoomAutoPosition is buggy apparently, the Tumbleweed template's 2nd room is twice as wide and Roger ended up halfway between the room's center and edge, suggesting that AGS uses the distance from the center to calculate the new position, not the distance from the edge.

(In other words, it fails to position the character along the edge in the new room.)

If this is a regression and hasn't always behaved this way, it should be fixed for backwards compatibility. I cannot test that right now, but I'll try when I can. (And as a minor point, the documentation should be edited to be gender-neutral. I think "it" should be the preferred pronoun for characters.)

Going forward, I propose that the whole function be deprecated, since its API is fundamentally incompatible with an engine supporting larger resolutions/room sizes. If the functionality is desired in the engine, a new function with an API like the version I wrote in AGS Script could be provided:

Code: ags

Character.ChangeRoomEdge(int room_number, optional RoomEdge edge, optional int edgePosition)

(As in my implementation, I also propose removing the 10 pixel condition, and pick the room edge the character is closest to/furthest outside as the exit edge, no matter the distance.)