Topic: Features suggestion: autocomplete custom properties + disabling them

[Lord Vetinari]

The title is kinda cryptic due to title length limitations, I'll try to explain more here.

Baically, I've been using custom properties a lot recently, mostly to consolidate stuff and track/set custom statuses. So, for example, I have the inventory items custom properties "batteryCharge" and "powerSetting" (think Star Trek phasers with stun and kill settings for this one, ans ammo for the other one), which allows me to have a single laser gun that behaves differently depending on those properties without the need to create multiple inventory items and swap them to represent the different statuses of the gun. I don't know if this was the intended use for custom properties, anyway it works really well and I find it easier to wrap my mind around design this way for this kind of purpose.

I have two tiny gripes with the custom properties used this way, though: the first is that the editor does not autocomplete or indeed recognize if what you're writing is a thing until you compile, which means that I have to either write down their names on paper or keep opening the custom properties window to check the correct spelling, and I'm missing the easiness of use that comes with the ability to choose one item from the autocomplete list rather than manually typing their names.

The second is that you can only create custom properties per broader categories (i.e, all objects, all inventory items, all rooms, etc), which means that when I use this approach a lot, I end up with a long list of mostly useless properties that are meant to be relevant for one or two objects/rooms/chracters/etc and instead pop up in every single same-type-thingie I create in the rest of the game (the iBucket doesn't need batteryCharge nor powerSetting, but it may need the fullnessThresholds one that is however useless for the iGun, and so on. This would become an even bigger problem if autocomplete will ever be added). Not a big issue per se (even though I don't know how big an impact a large amount of custom properties have on the game's performance and memory usage, if any), but sometimes tracking down the right property in the middle of the other useles ones becomes more tedious that it should be.
Would it be possible to add the option to enable/disable any property from any specific item/object/etc (or at least hide it from it's properties list)?

[Snarky]

The lack of autocomplete is a consequence of the fact that custom property names are arbitrary strings. There's really no feasible way to make autocomplete happen while that is the case: they'd have to be fundamentally reimplemented some other way.

However, you can get access to autocomplete by using #define statements to make constants for the strings you need:

Code: Adventure Game Studio

1. #define ipBatteryCharge "batteryCharge"  // "ip" for "inventory property"
2.  
3. function someFunction()
4. {
5.   // ...
6.   int charge = iGun.GetProperty(ipBatteryCharge); // Should autocomplete
7. }

You can put the #define statement in your GlobalScript header to make the constant available in room scripts.

(By convention, constants are usually all uppercase, but I think it's worth making an exception in this case.)

For the other issue, that probably means you're using custom properties in a way they're not meant to be used. If you have some property that only applies to one particular instance of a type (like an inventory item), you should just use a variable to store it. For example, if you just have a single gun in the game, there's no need to add batteryCharge and powerSetting as custom properties to all inventory items: You can just have them as global variables.

If you have a whole bunch of related variables that describe some type of object, and particularly if you can have more than one instance of that object, that's when you want to use a struct. For example, let's say you have a bunch of space ships with different stats:

Code: Adventure Game Studio

1. struct SpaceShip
2. {
3.   String Name;
4.   int View; // The view number for this ship
5.   int CargoCapacity;
6.   int PassengerCapacity;
7.   int MaxSpeed;
8. };

Now you can create different space ships. For example:

Code: Adventure Game Studio

1.   SpaceShip millenniumFalcon;
2.   millenniumFalcon.Name = "Millennium Falcon";
3.   millenniumFalcon.View = VMILLENNIUM; // The name of a view
4.   millenniumFalcon.CargoCapacity = 120;
5.   millenniumFalcon.PassengerCapacity = 6;
6.   millenniumFalcon.MaxSpeed = 16;

And if you then have a Character called cShip that represents your current space ship, you might set it to the Millennium Falcon like so:

Code: Adventure Game Studio

1.   cShip.Name = millenniumFalcon.Name;
2.   cShip.ChangeView(millenniumFalcon.View);

[Lord Vetinari]

Didn't know about #define, that'll be useful, thank you.

As for the structs, going with your example I'll have to then check either via if-else or switch cases which SpaceShip is currently assigned to cShip if I want to get any use out of those nice extra properties like CargoCapacity, and the more SpaceShip instances there are, the messier the function becomes (unless I'm missing something relevant). Also less easier to expand in case later down the line I decide to add new ship classes.
The code becomes much more straightforward and easy to read (especially if you check it back some time later) if I can simply do something like

Code: Adventure Game Studio

1. void LoadingCargo(int TransferredCargoSize, int CargoID) {
2.   if ((TransferredCargoSize <= cShip.GetProperty("CargoCapacity") && (cShip.GetProperty("IsCargoHoldFull") == false)) {
3.     cShip.SetProperty("IsCargoHoldFull", true);
4.     cShip.SetProperty("TransportedCargo", CargoID);
5.   }
6.   else {
7.     Display ("sorry, we have no room for that");
8.   }
9. }

Nine lines, done, and it'll work with any CargoCapacity value I'll ever assign to cShip. But this on the other hand means that I'll find all my non-ships characters with CargoCapacity and all the other stuff that they don't need attached.
How can you do the same as easily with structs?

[Snarky]

As for the structs, going with your example I'll have to then check either via if-else or switch cases which SpaceShip is currently assigned to cShip if I want to get any use out of those nice extra properties like CargoCapacity, and the more SpaceShip instances there are, the messier the function becomes (unless I'm missing something relevant). Also less easier to expand in case later down the line I decide to add new ship classes.

No, that shouldn't be necessary. There are a couple of ways to it, depending on your exact needs.

One is to use a managed struct with a pointer (I've added a couple of bells and whistles to the code to show you what's possible; you don't strictly need all of this):

Code: Adventure Game Studio

1. // SPACESHIP MODULE HEADER
2. managed struct SpaceShip // We've just added the tag "managed"
3. {
4.   String Name;
5.   int View; // The view number for this ship
6.   int CargoCapacity;
7.   int PassengerCapacity;
8.   int MaxSpeed;
9.  
10.   // And let's add some more properties for the current ship status:
11.   int CurrentCargo;
12.   int CurrentPassengers;
13.   int CurrentSpeed;
14.  
15.   // We can also add functions:
16.  
17.   /// Make this SpaceShip your current ship
18.   import void Select();
19.  
20.   /// Load cargoAmount. Returns whether the cargo could be loaded.
21.   import bool LoadCargo(int cargoAmount);
22. };
23.  
24. import SpaceShip* myShip;
25. import SpaceShip* millenniumFalcon;
26.  
27. // SPACESHIP MODULE SCRIPT
28.  
29. // This is a variable that should always refer to your current ship
30. // (the same way "player" always refers to the current player Character)
31. SpaceShip* myShip;
32. export myShip;
33.  
34. SpaceShip* millenniumFalcon; // If you have a lot of different ships you'd probably store them in an array instead
35. export millenniumFalcon;
36.  
37. // You need to make sure this function is called, ideally on game start
38. function InitializeSpaceShips()
39. {
40.   millenniumFalcon = new SpaceShip;
41.   // ... Otherwise same as before
42. }
43.  
44. void SpaceShip::Select()
45. {
46.   myShip = this;
47.   cShip.Name = this.Name;
48.   cShip.ChangeView(this.View);
49. }
50.  
51. bool SpaceShip::LoadCargo(int cargoAmount)
52. {
53.   if(this.CurrentCargo + cargoAmount > this.CargoCapacity)
54.     return false;
55.   this.CurrentCargo += cargoAmount;
56.   return true;
57. }

Now you can call millenniumFalcon.Select(); to set your ship to the Millennium Falcon, and instead of cShip.GetProperty("CargoCapacity") you would just use myShip.CargoCapacity, or even the custom function for loading cargo we just made:

Code: Adventure Game Studio

1. void LoadingCargo(int transferredCargoSize) {
2.   if(!myShip.LoadCargo(transferredCargoSize))
3.     Display ("Sorry, we have no room for that");
4. }

And then you could do it in 4 lines of code!
(You're not really saving much code, just moving it into SpaceShip.LoadCargo() instead.)

If you don't want to use managed structs (or you're using an older AGS version that doesn't support them), you would have to work with arrays and copy functions and so on. That's a good deal more tedious.

As you see, you're essentially doing just the same thing as with custom properties, except that instead of adding the properties to (in this case) the Character type, you're making a type called SpaceShip and adding them to that. With just a few lines of code to link the Character to the SpaceShip, you get all the benefit without adding any clutter to other Characters.

Edit: Fixed typo in code

[Lord Vetinari]

I'm using 3.4.0, the latest official release (since 3.4.1 isn't officially out yet).

Wait, so there's been managed structs in AGS for this whole time? The wiki says that there weren't and has even a lengthy and rather scary article on how to fake custom struct pointers.
I've been bashing my head against the lack of custom types pointers for such a long time! Admittedly I'm doing something that probably is not meant to be done in AGS, that is a game with a significant survival/simulation component in which you start from scratch, update your tools, have to manage the character's stats, etc, and I've been doing all of that with custom properties because I thought I couldn't use structs.

I'm not that obsessed with the overall lenght of the code, I just don't want to have overly long functions that you don't understand anymore a week after you wrote them no matter how many comments there are. "Encapsulating" stuff (ok, I know it's not proper encapsulation as it's all public, you get what I mean) in structs is perfectly fine.

Given this, I'll probably have to rewrite half my game, but that's a huge relief. Thanks!

[Crimson Wizard]

Wait, so there's been managed structs in AGS for this whole time? The wiki says that there weren't and has even a lenghty and rather scary article on how to fake custom struct pointers.

User managed structs were introduced in 3.4.0, but there is a technical limitation that you cannot put another managed pointer in such struct. I know that's silly, but there is a serious reason for that that was not yet solved.

Wiki is like 10 years old compared to recent release, it is not even updated to AGS 3.2.1 (last version made by Chris Jones).
(I feel like repeating this for the 10th time in past couple of years, because people keep getting into similar situation ).

I strongly advise to check for "Upgrading to AGS X.X" topics in the manual you have with the AGS Editor (you can call it with F1). These articles note most important additions and changes.

[Lord Vetinari]

Thank you. No pointers in structs shouldn't be a huge issue in my case (after all, I already wrote a significant part of the "survival" logic using properties, which do not allow pointers either).
I'm not too keen on starting from scratch, at least for now I'll probably just move all that stuff to structs and update the global script functions to reference the structs instances' members rather than the custom properties.

Thank you all!