Inconsistency in the AGS language

[Joacim Andersson]

I've been reading through the AGS documentation, the help file that AGS is shipped with, and found some inconsistencies in the language. I know that Chris Jones, an Englishman, originally created AGS, so the spelling Colour makes sense, however for a DrawingSurface it's suddenly spelled DrawingColor, shouldn't it be DrawingColour? Also, the X and Y coordinates for an Object use capitalization as opposed to character placement, I'm guessing that this has to do with Room coordinates vs Screen coordinates so I'm fine with that but shouldn't then the parameters of the DrawXXX methods for a DrawingSurface also use capital X and Y?

I might be picky here, but I wondered about the consistency.

[eri0o]

I doubt this is as profound. CJ started this thing in 1997 and was very young and used C so I guess things are trying to be C-like, it's DOS era. At some point people appear more interested, Java appears, OoP starts to be a thing people care about, CJ starts using some version of C++ in ags along of C code. It appears a graphical ide is interesting, a C# IDE gets written, and inspired by OoP and C#, starts some work putting OoP in the script API. More people are interested in AGS, there's a lot of expectations and development ceases to be fun. Global users are interested and they use American English in written convey. AGS is open sourced, CJ leaves the scene, people try to continue the work in the way it felt like it was headed, more British gets dropped from the API slowly. Novelty around open source of AGS dies soon, until it's very few people (mostly CW) pushing the engine forward. Meanwhile AGS keeps all this backwards compatibility - you can still boot your 20 year old project and load in the current Editor. AGS also keeps binary compatibility between runtime and old games - you can still run a 20 year old game in the current engine. Things that aren't a priority aren't replaced in the API - it's a lot of work to do so and keep backwards compatibility. That's pretty much how I read this, in the previous era the parameters in functions were a_word and then after C# gets used they slowly became aWord, and so on. I've been here since more recent years so I didn't lived in the previous era, I just read through the history to figure out things for the engine...

[Crimson Wizard]

In summary: script API contains numerous layers, some ~20 year old. We are trying to be consistent with the chosen naming style when we add new things, but unless we replace old things completely they remain. And replacing old things randomly make old users unhappy; in fact any replacement makes users unhappy: since certain time the tech support forum is littered by questions like "where did command xxx go, it used to work, but now it's not recognized".
The only things that are "safe" to rename until now are function parameters, but that's because user does not have to type these, you only see them in tooltips.
(and then there's a new proposal for ags4 script compiler, to support function parameter list with named args, which may make this suddenly more fragile)

The chosen naming style used today is this:
- Names of structs and functions is in CamelCase.
- Names of attributes (aka properties) in structs is in CamelCase. Character.x,y is a very old inconsistency, because this struct was probably among the first to be added to script API.
- Names of function parameters are in camelCase with the first small letter (hence it's property 'X', but parameter 'x').
- Names of raw variables, whether global or struct members, is in small case with underscores (iirc), but we try not to add these to API today, so 99% of those are remains from non-OOP API times.

We might fix inconsistencies more in AGS 4, where breaking backwards compatibility is expected.

[eri0o]

@Crimson Wizard , this reminds me, should the named parameters in ags4 be behind some flag? Other thing, there are parameters that aren't named at all in the script API, usually enums, we may need to name then.

[Crimson Wizard]

@Crimson Wizard , this reminds me, should the named parameters in ags4 be behind some flag?

Do you mean parameters in script API, or the compiler's feature?

[eri0o]

The new compiler feature. Though I guess this should mostly be a minor issue, since it will affect projects if we rename some parameter but not binary releases. But my idea of the check would be mostly so that people understand that they may have to adjust their code if they use it in an interaction with external code - be the script API of the engine or a module.

[Snarky]

And replacing old things randomly make old users unhappy; in fact any replacement makes users unhappy: since certain time the tech support forum is littered by questions like "where did command xxx go, it used to work, but now it's not recognized".

A while back I thought to add an feature request to the AGS github about adding "deprecated" warnings/errors to the compiler, so that if there's some change to the API (like removing System.ViewportHeight/Width), users could get a more helpful message than the generic "Undefined token" or "'[Field]' is not a public member of '[Struct]'" error message you get currently.

I think that would make it a lot less problematic to make such changes.

But then it looked like there were references to that feature already being in place, so I'm not sure what the problem is?

[eri0o]

I think in the hypothetical world where script compiler supports this you still get this same error message, you could only get the deprecation warning if you build with a Script API setting that allows using an older API.

Like

Code: ags

 #ifdef SCRIPT_COMPAT_v350
/// Returns which walkable area is at the specified position on screen.
[[Deprecated: see WalkableArea.GetAtRoomXY]]
import int  GetWalkableAreaAt(int screenX, int screenY);
#endif // SCRIPT_COMPAT_v350

Will only be available if the compatibility is defined, so you would lower the compatibility, which I think is done by default when you upgrade the editor in a previous project - actually, it just doesn't go up.

[Snarky]

So what does that annotation actually do? If I set the script compatibility level to "3.5.0 Alpha" or earlier it compiles without any complaint or warning, and there is no indication anywhere I can see (outside of the manual) that GetWalkableAreaAt is deprecated.

The example just seems to show it has to be done differently if this feature is to be supported. There has to be a part of the API that is defined and recognized (at the selected script compatibility level), but throws an error if actually referenced in the script.

Possibly there is a need for two different deprecation levels:

Warning: Works in this version, but no longer recommended to use; may not work in future versions
Error: Worked in previous versions, no longer works in this version

[eri0o]

Are you suggesting something for now to the future, or like, resurrecting the gazillion lines of API that were deleted from the land before time in ags4?

What we do currently in the API ignores the compiler, it's solved before, in the preprocessor. One would need to properly imagine how this idea proposed would work with some annotation. I don't have a good idea for this - the compiler doesn't know about the APIs at all today, and the script header for the engine script API has nothing special vs any other script header.

[Snarky]

What we do currently in the API ignores the compiler, it's solved before, in the preprocessor. One would need to properly imagine how this idea proposed would work with some annotation. I don't have a good idea for this - the compiler doesn't know about the APIs at all today, and the script header for the engine script API has nothing special vs any other script header.

Well, I'm not familiar with how the compiler works, but my thinking is that when some element has been annotated, that sets a flag on it, so that when the compiler comes across it being referenced, it throws an error. That it doesn't distinguish the script API from any other script header isn't necessarily a problem—it might even be a good thing to expose the ability to annotate things in this way for module writers.

Are you suggesting something for now to the future, or like, resurrecting the gazillion lines of API that were deleted from the land before time in ags4?

I mean, the main thing is to implement it for the future, but if someone then wants to go and add annotated deprecated/obsolete hooks for commonly used APIs that have been removed, that wouldn't be unwelcome (as long as it doesn't show up in the IDE autocomplete, or at least shows a deprecated warning in the tooltip).

[eri0o]

I guess this idea is something to sit on for a little to come up with a good design that works, since these decisions tend to stick for a little while. I don't think what we have now is bad necessarily, so I would look to fixing other things (higher priority things, for me) and let more people comment and improve this idea for some time.