Documentation for overlays and characters Zorder and baseline

[jumpjack]

I think the documentation about this new ZOrder feature introduced with 3.6.0 could be more clear by adding a reference to characters and objects baseline.

Current description:

Overlay.ZOrder
int Overlay.ZOrder;
Gets/sets the overlay's z-order relative to other overlays and on-screen objects.

The Z-order setting is an arbitrary integer number that can be positive or negative. AGS draws the Overlays and GUIs in order, from the lowest numbered at the back to the highest numbered at the front.

Compatibility: Supported by AGS 3.6.0 and later versions.

See also: GUI.ZOrder

Suggested changes (in bold):

Overlay.ZOrder
int Overlay.ZOrder;
Gets/sets the overlay's z-order relative to other overlays and on-screen objects.

The Z-order setting is an arbitrary integer number that can be positive or negative. AGS draws Overlays, Characters and GUIs in order, from the lowest numbered at the back to the highest numbered at the front. Overlays support transparency, so they can also be used to define walkbehind-like areas starting from sprites:

myOverlay[overlayIndex] = Overlay.CreateRoomGraphical(x,y, spriteSlotNumber, 0, true);

The player or object will be drawn behind the overlay if condition

player.Baseline < overlay.ZOrder

or

object.Baseline < overlay.ZOrder

is true.
Normally player baseline value is automatically set by AGS engine to same value of player.y (lowest edge of sprite), but it can be set to any value; if set to 0, it switches back to auto-handling by AGS.

Compatibility: Supported by AGS 3.6.0 and later versions.

See also: GUI.ZOrder

[jumpjack]

Some images to better explain both Zorder and baseline (hoping that I understood correctly...):

Apparent misbehaviour due to character Y offset w.r.t. its actual baseline: an object should apparently be drawn behind the object (because feet are higher than object baseline), but is drawn in front of it:

How ZOrder works (independently of baseline):

Visual error if sprite image is not exactly aligned to bottom edge:

[jumpjack]

Further improvement:

This part:

could probably improved by a further note:

if the dynamic sprite variable used to create the overlay goes out of scope, the overlay will not be removed, but its reference to the sprite will become invalid and automatically set to default sprite slot n.0. Hence, if you want the overlay to last on-screen outside of the script function where it was created, you have two choices:

• the Overlay must be created as a copy, by setting last parameter ("clone") to "true"
• the dynamic sprite must be declared outside any function, so it will not get destroyed once the function ends (to be verified)

[ivan-mogilko]

Overall, I think this information about how sorting order works is shared among several kinds of objects. Therefore it's better to put it in a separate article, while adding a link to that article in Overlay.ZOrder, as well as other related ones (like Character.Baseline, Character.y, GUI.ZOrder, and so forth).

[ericoporto]

Room overlays, character, objects and walkbehinds are sorted inside the "room" and the GUIs and Overlays are sorted on "top". This new article do we want it only about sorting or we want to include something on the coordinates too?

[ivan-mogilko]

This new article do we want it only about sorting or we want to include something on the coordinates too?

Which information about coordinates are you referring to?

Regarding article, I think we need a section about engine behavior, as briefly proposed in #209. The article itself may be called simply "Objects draw order" and contain necessary info to understand how objects are sorted among each other.

EDIT: the article may be placed under "Engine" for now. The amount of documentation is so low there, that you won't be able to organize it better at the moment.

[ericoporto]

Some images to better explain both Zorder and baseline (hoping that I understood correctly...):

baseline == Zorder, it's a number, things are ordered by that number, big numbers are placed forward, small numbers placed backwards. What happens when numbers are the same? That is a mystery, but for GUIs they follow the order of IDs. I have no idea what happens if they are other types of objects or objects of different types mixed together when zorder is the same.

Generally in rooms we say baseline and in GUIs we say Zorder. Things in AGS have names for historical reasons, like why is YOffset named Z and things like that.

Which information about coordinates are you referring to?

Overlay and GUI coordinates are native screen coordinates, GUIControls are relative to owning GUIs, these object coordinates reference their top left corner. Characters, Objects, and Room Overlays are in room coordinates, where Camera and Viewports exists, complicated explanation about character feet object is bottom left, transformations, yada yada. You know, it all makes sense but we really need drawings somewhere.

Perhaps it's best to leave coordinates to some other article.

[ivan-mogilko]

What happens when numbers are the same? That is a mystery, but for GUIs they follow the order of IDs. I have no idea what happens if they are other types of objects or objects of different types mixed together when zorder is the same.

For GUIs they don't follow the order of IDs either in the latest build. This is a strange situation, but the draw sort does not refer to IDs at all, only clicking detection. I'm not sure why it was done so. It's possible this could have changed somewhere, maybe in 3.6.0 when the sorting of Overlays was added. I need to double check that.
EDIT: ah, so that's another oversight, similar to the clicking detection bug that I was fixing recently. This got to be fixed, at least in regards to GUI.

For room entities (room objects, characters, walk-behinds, room overlays) the order of 2 elements with equal zorder is currently undefined.
EDIT: correction: there's a special rule for walk-behinds, it looks like walk-behinds with same baseline are always drawn above characters and objects (may require double check).

GUIControls are relative to owning GUIs, these object coordinates reference their top left corner. Characters, Objects, and Room Overlays are in room coordinates, where Camera and Viewports exists, complicated explanation about character feet object is bottom left,

Now when you mention this, sprite anchoring relative to the object position may belong to the same article. This may eventually be a big article that explains how sprites are drawn on screen, where sorting is a sub-section.

[jumpjack]

baseline == Zorder

By the way: I think the fact that "player.Baseline = 0" means "automatically set baseline to lowest edge of player" is quite misleading ("is current baseline value 0 or something else?"); maybe it would be better if in 3.6.0 a "baseline flag" is added, something like "player.baselineAuto = true/false"; if set to "true", writing to player.Baseline should cause an error, being it managed by engine, and player.Basline should always contain the Baseline value iternally seen/used by the engine.
Currently, instead, there is a "secret variable" which contains the actual value of Baseline when player.Baseline is set to 0.

It's an issue similar to sprite slot 0 automatically assigned by the engine: the engine should never decide on its own to overwrite variables set by developer (IMHO), but only act on "reserved" variables, which should appear as readonly to developer.

[ivan-mogilko]

maybe it would be better if in 3.6.0 a "baseline flag" is added,

We are not adding anything new to 3.6.0 now, the version is close to the stable release. So this has to be left for the future consideration.