Asking for advice about Name/ScriptName/Description term discrepancy

[Crimson Wizard]

For a long time there is a discrepancy between terms used for object properties in the Editor UI and the script.

Something that is called "Name" in the Editor is used to generate a script variable for an object and is called "ScriptName" in script api (e.g.: Character.ScriptName).

Something that is called "Description" in the Editor is used when displaying an object's name under a cursor, and is called "Name" in script api (e.g.: Hotspot.Name).

An exception from the above is Character, whose "description" property is called "RealName", although it's still just "Name" in script.

I did a little research and found that back in 2.* editor these fields were called more consistently: the "Name" was used for "human readable name", and it was Name in script too; while the scripting name field was labelled "Script O-Name" (probably short for "Script Object Name").

(Character's fields were standing out back then though, as they had a "Full name" rather than just "Name").

If we take a script, historically term "Name" was used for "human readable name" or "description". Properties like Hotspot.Name, Object.Name and Character.Name existed for a long time. Same as function GetLocationName which returned a "description" rather than a "script name".
https://adventuregamestudio.github.io/ags-manual/Hotspot.html#hotspotname
https://adventuregamestudio.github.io/ags-manual/Game.html#gamegetlocationname

This situation may be summarized in the table:

v2 Editor	v3 Editor	Script API	meaning
Name	Description	Name	human-readable text, description
Script O-Name	Name	Script Name	unique identifier, variable name

This difference in v3 Editor is causing confusion when a user is trying to use properties like Hotspot.Name in script and finds out that it returns "Description". Or when a user is trying to get Description in script, but does not find such property at all.

I also made a mistake recently, when added GetByName functions to all objects, which looks up for an object using its script name. I think I chose such name because it's shorter than GetByScriptName. But it may introduce further problem.

What would be a good way to solve this problem?

The easiest solution that I found is to change labels in the Editor like this:
Name -> ScriptName
Description -> Name
By "easiest" i mean that this won't cause any compatibility problems, as only labels are changed. Project data and script commands remain the same. But of course this will change what user sees in the property grid.

And there's still a question of "GetByName" script function.

There's a issue opened recently, caused by this difference: https://github.com/adventuregamestudio/ags/issues/2823
and my proposed changes as a PR:
https://github.com/adventuregamestudio/ags/pull/2824

But since there are doubts, as mentioned in conversation, I am unsure how to proceed.

[Crimson Wizard]

The situation may be more complicated though. The "Name" term is generally more suitable for "unique identifier" in editors of all sorts. And not every item in the game has a script variable associated with it, so "Script Name" may not be used everywhere. That could be the reason why Chris Jones turned to using "Name" as id and "Description" as a human-readable object name.

If I were writing a new engine from scratch, I would certainly use "Name" as a unique id, and something else for a text that is associated with the object in game (I can see variants here, like, "Label" etc).

But it's a mess currently in AGS.

[Danvzare]

I wish I knew what to suggest.
On the one hand, that simple solution you suggested, sounds like the most reasonable course of action. But as you elaborated later, it still creates some problems. Then of course there's the potential for compatibility issues if you go for anything more drastic.

It might be a good idea to avoid "Name" altogether.
Perhaps something like:
Name -> Unique Identifier
Description -> Description

Then change the functions to match (such as Hotspot.UI and Hotspot.Description).
Maybe keeping the older functions for a short while for backwards compatibility.

But that's just my idea. I trust whatever you decide more than anything I come up with myself.