Deprecate 'function' keyword

[messengerbag]

Describe the problem The function keyword is a legacy of ancient AGS scripting. Many of the default functions that are called by the engine use it as their return type. Because it is implemented as an alias of int but is used even if the function doesn't actually return anything, it means that AGS script cannot properly distinguish int and void return types.

It also creates inconsistency, with two/three different ways to write the same function. This arguably creates confusion and makes the AGS scripting language harder to learn.

Suggested change Remove function as a keyword. Change all function definitions to use int or void as appropriate, and make sure the editor uses these when creating event handlers. This also requires an update to the manual and to the templates.

Optionally, update the compiler to require a correct return type (do not allow a bare return; if the return type is declared as int, or a return 1; if the return type is declared as void).

Optionally, add a backwards script compatibility option to retain function as a keyword (still as an alias for int). (Note that if the other optional part is implemented, this would still require users to change all functions that need to have void as their return type, unless that is also disabled if the script compatibility option is set.)

Alternative suggestion Alternatively, don't remove function as a keyword, but change all the built-in functions to either int or void as appropriate (including in the manual and templates), so that function never appears unless you specifically add it.

[AlanDrake]

I guess I'll go check the manual for old examples with function.

EDIT: There are are 147 references, of which most are event handlers. Do we want to start steering users away from function right now? If so, I could start with references that aren't event handlers, since those are still created as function xxx() by the editor and writing them differently in the manual could be confusing, unless we're also planning to update 3.x soon to discourage the legacy keyword.

[ericoporto]

About ags3 , check https://github.com/adventuregamestudio/ags/issues/1331#issuecomment-877709952

I think void in ags3 is actually int for compatibility because some old games returned something in a void function and it was kept to avoid breaking old games.

[messengerbag]

Yes, I thought so. That's part of why I think AGS 4.0 is a good opportunity to fix it.

[ivan-mogilko]

I think void in ags3 is actually int for compatibility because some old games returned something in a void function and it was kept to avoid breaking old games.

To clarify, today void is a valid keyword in compiler and not an int alias, but the engine "secretly" still returns a integer '0' from the functions of void type. This is done because old API was not declared as void but as function, even though it did not return anything meaningful, and unfortunately some users have used this return value by mistake.