Script API: add Room.Name and Room.Number

[ivan-mogilko]

Resolves #1135.

Adds 3 static readonly properties to Game struct:

/// Gets the total number of the rooms in game.
static readonly attribute int Game.RoomCount;
/// Gets the existing room numbers by a sequential index (from 0 to RoomCount - 1); returns -1 if index is not valid.
static readonly attribute int RoomNumbers[];
/// Gets the room's name (description) by the room's number; returns null if such room does not exist.
static readonly attribute String Game.RoomNames[];

Adds 2 static readonly properties to Room struct:

/// Gets the current Room's number
static readonly attribute int Room.Number;
/// Gets the current Room's name (description)
static readonly attribute String Room.Name;

The only caveat is that room descriptions were not saved in the room itself, so I had to add them to room format.

[ericoporto]

The only caveat is that room descriptions were not saved in the room itself

I may be misremembering, but I thought the debug command that can teleport (used with Ctrl+x in templates) had the room names in the list.

The clang error looks like you already fixed so just a rebase should fix it.

[ivan-mogilko]

I may be misremembering, but I thought the debug command that can teleport (used with Ctrl+x in templates) had the room names in the list.

That's true, but these are saved in the game data instead of the room...
and only in debug configuration

...which makes me wonder if we need an array of room names in Game struct too.

[ericoporto]

Other thing that I remembered is I believe all other game elements have names that are also writeable. I don’t know how useful this is in regards to room names, I imagine most of cases where a location changes enough to change name it also will be an actual different room - unless it’s something like a room for a character you don’t know that later you get to know - say “Apartment” becomes “Jane’s Apartment” or something.

I guess there is also the Name and the scriptName, in theory - where the scriptName is read-only.

If the room name here is intended for using in debug guis it is fine, I am mostly thinking about say the character enters the room and the room name shows up on screen, or you save and the room name is added to the save description.

[ivan-mogilko]

Added Game.RoomCount and Game.RoomNames[] properties.

There's an obvious problem with these two. Rooms are not sequential and RoomNames[] may have gaps with null elements, similar to sprites for example.
Because of that RoomCount has a dubious meaning. It's not the "length" of RoomNames, but just a report of how many valid elements are there.
I'm not certain if that's acceptable.

Here's a script that I used as a test, that fills the list of rooms:

    for (int room = 0, total = 0; total < Game.RoomCount; room++)
    {
      String name = Game.RoomNames[room];
      if (name != null)
      {
        ListBox1.AddItem(String.Format("%d: %s", room, name));
        total++;
      }
    }

One option that I might think of is to have a separate RoomNumbers[] property, that returns a sequence of valid room numbers.

---

I guess there is also the Name and the scriptName, in theory - where the scriptName is read-only.

I added "script name" field in the previous commits, but it's reserved and does not have any value atm.

I don't know if changing room name is necessary, but that may be added without problem when needed.

[ericoporto]

Uhm, we now can retrieve dynamic arrays from functions. Don’t have any idea on this yet but we could avoid the RoomCount name problem by letting the user figure it out from the Length property.

One option that I might think of is to have a separate RoomNumbers[] property, that returns a sequence of valid room numbers

I don’t have a good idea to name a Room Count that is specifically to numbers, AvailableRooms may be too verbose but it’s more clear in which room count we are talking and perhaps if the type is an int people understand it’s a number.

I don't know if changing room name is necessary, but that may be added without problem when needed.

Me neither. Perhaps people may use custom properties more easily now that they are right there in the properties so maybe at least that workaround is easier to use - I have a RoomName custom property in my games.

[ivan-mogilko]

Uhm, we now can retrieve dynamic arrays from functions. Don’t have any idea on this yet but we could avoid the RoomCount name problem by letting the user figure it out from the Length property.

I would not want to return dynamic array here, because it means create new array of elements and copy all data over, while user may want to retrieve only 1 string.

And then, that will not fix the problem, because either array indexes correspond to room numbers, and then there are gaps again, or they are "squashed", in which case you won't be able to tell which rooms that are.

---

I don’t have a good idea to name a Room Count that is specifically to numbers, AvailableRooms may be too verbose but it’s more clear in which room count we are talking and perhaps if the type is an int people understand it’s a number.

What I meant is to have something similar to this:

int RoomCount;
int RoomNumbers[]; // access sequentially 0 to RoomCount
String RoomNames[]; // access by room ID (has gaps)

Then iterating rooms would look like

for (int i = 0; i < Game.RoomCount; ++i)
{
     String name = Game.RoomNames[Game.RoomNumbers[i]];
}

[ericoporto]

for (int i = 0; i < Game.RoomCount; ++i)
{
     String name = Game.RoomNames[Game.RoomNumbers[i]];
}

I didn't had any idea better than this other than retrieving these as an AGS dictionary - keys as numbers and values as names. Perhaps it has the same issue as dynamic array - unless it's created on game start and a ref is hold forever.

I guess we can just rename the Description in the Editor property as Name too - perhaps not the actual property, only the name that appears in the property grid.