[Feature Suggestion] Auto-link event handlers

[Snarky]

One of the most common newbie errors is to not link an event handler to an event property, so that the function never runs. (And honestly, not even just a newbie error, though more experienced AGS devs know how to fix it on our own.)

So I was thinking: why not do it for them? At compile time, for each event property that doesn't have an event handler set, check if the default function name (with the correct function signature) exists in the relevant script, and if so, automatically link it. (Probably with a warning in the output pane, or maybe even a popup dialog box.)

[Gurok]

Nice idea. Perhaps even with support for an annotation a la

Code: ags

// $AUTOCOMPLETEIGNORE$

that will tell the compiler not to spit a warning for a particular function.

[Crimson Wizard]

For this to have any progress, we would need a more detailed specification on how such feature would work, on which stage and which part of the program is responsible for this. Also, what's the input and the output, so to speak. Is this auto-link a one time operation that changes the project data, or it has only an effect on the output data (and thus fully repeated each time a game is recompiled)?

For one example, in regards to the compiler's warnings; a script compiler does not know anything about object links or objects themselves. This information is stored in a different data source which is not a part of a script compiler's input. Therefore it cannot make such warnings. Something else might (an extra process before compiling the script?).


On similar topic, I recall there have been another suggestion, where room handlers should be fully automatic, because there can be only 1 room loaded at a time.

On another hand, there's an idea of supporting delegates, where one would be able to link multiple handlers to the same event, right in script. Will that conflict with the above ideas in any way?

[eri0o]

I would have it signed on the left bar with a lightning bolt if it's linked by something, and if matches the style of something that's normally linked but it's not linked, have an exclamation, like this ⚠️.

Or would at most produce a warning right now.

I wouldn't automatically link things right now until the delegates idea advances, since that would probably change things.

[Crimson Wizard]

I would have it signed on the left bar with a lightning bolt if it's linked by something, and if matches the style of something that's normally linked but it's not linked, have an exclamation, like this ⚠️.

Sorry, I did not understand this sentence. Which "left bar" are you refering to?

I wouldn't automatically link things right now until the delegates idea advances, since that would probably change things.

Change things how, theoretically? Whether one idea contradicts the other depends on what is implied by both of these features. But it may only be seen if the idea is elaborate.

Afaik the idea of a delegate implies to have an "event" or "function pointer" type of property in classes, which may be set or unset in scripts, at runtime.
The "automatic linking", at least from what I see in posts above, suggests to utilize already existing functionality of binding a script function to event at design time. That is, something is done automatically in addition to manual work (which can be done anyway).

I would also not recommend to wait for the implementation, as, knowing how AGS progresses, delegates may never be implemented, or implemented 5 years later. IMO it's best to decide on theoretical goals; knowing goals would let us know what is safe to consider and implement, and in which direction to develop.

[Snarky]

The theoretical goal here is to help users avoid this common mistake. As mentioned in the post where I linked to this thread, on second thought I think it's better to provide some kind of warning in the editor than to actually auto-link the event.

So the behavior I propose is this: When a user gives a command to build the project, the process detects if there are any functions (currently only in GlobalScript or a room scrip) that match the signature of the default event handler (i.e., matches the function name that would be auto-generated, and has the right argument list) for any event, but isn't linked to that (or any other?) event. If so, it produces a warning that is displayed to the user (in the editor, in the default case). Optionally, there could be a way in the editor to "automatically" resolve the issue by for example double-clicking on the warning to link the function to the event.

As Gurok adds, there should also preferably be some way to turn off this warning for a particular case, though I don't think this is essential.

I don't think this is incompatible with the delegate idea, unless we move to a system where you no longer link event handlers in the property pane at all (i.e. no longer defined in the project file), but always hook them up via code.

For one example, in regards to the compiler's warnings; a script compiler does not know anything about object links or objects themselves. This information is stored in a different data source which is not a part of a script compiler's input. Therefore it cannot make such warnings. Something else might (an extra process before compiling the script?).

Sure. I don't think it makes much difference to the user what internal process is responsible.

Sorry, I did not understand this sentence. Which "left bar" are you refering to?

I'm fairly sure eri0o means the column to the left of the code editor where you can set breakpoints, do code folding, etc.

In general I think it's a nice idea to use it more to display errors, warnings, etc. I'm unsure whether marking event handlers would be helpful or just add clutter.

It also suggests that the analysis might happen as you type rather than at compile time, like in Visual Studio. That seems like a more ambitious idea.

[Crimson Wizard]

If done upon the compilation, the script compiler gathers a list of functions, which one may request and pass to the "upper level", where it's compared with the patterns and check existing events as a post-compilation step.

I also know that some compilers optionally warn about functions that are defined but never called from within the program itself.

[Snarky]

OK, so to me that suggests that the proposal could be implemented as follows:

As a post-compilation step, go through every entity in the game project, and every possible event for each entity (that hasn't been linked to an event handler). Generate the default signature of the event handler for that event (as it would be created if you double-clicked on the event in the editor). Compare that signature to the list of functions returned by the compiler. If you get a match, emit a warning.

[Alan v.Drake]

I think AGS should auto-link events by naming convention unless expressly specified in the properties pane.
The possible drawback is renaming an object/character, but  we could add a step to perform a string replace in the room script, so it's not particularly lethal or anything.

A warning when there's no match to the specified script name, would be in order. Currently it fails silently to make sure you regret your life choices.


- Alan