Code Editor/Manual Content: sprite_delete() does return a success/fail value, despite the IDE/manual saying it does not return anything

[GameDevTosh]

Description

When using sprite_delete to delete a sprite created at runtime, the result returned by sprite_delete is 1 rather than undefined. The manual page states it should not return anything.

When deleting sprites saved in an array, there is no way to confirm the sprite has actually been deleted, as references still remain in the array. Talking with a few people, they've dubbed these garbage refs. However, we have no real way of confirming if these garbage refs will be collected when gamemaker garbage collects arrays, or if simply having those refs will keep the arrays alive or cause leaks. Sprite texture pages do turn to NULL in debug properly however.

Steps To Reproduce

The included project shows two examples.

The first example is by pressing spacebar. In this example, a sprite is created from a surface and stored in a variable. This new sprite is then deleted and the result is stored in a var, which is then shown on the console as 1.

The second example is by pressing Enter. In this example, a sprite is created from a surface and stored directly into index 0 of an array. We then delete the sprite in two ways. The first way is we delete the sprite from the array index and then store that result into the same array index, so:

temp_array[0] = sprite_delete(temp_array[0]);

In this first case, the result saved to the array is 1.

The second way is we delete the sprite directly from the array (after making a new sprite), such as:

sprite_delete(temp_array[0]).

In this second case, after displaying the array contents, we see the same ref as before. However, these are now considered garbage refs, but we have no way of confirming this, nor if the array will be garbage collected properly, nor if there are any leaks.

Which version of GameMaker are you reporting this issue for?

IDE v2024.4.0.137 Runtime v2024.4.0.168

Which operating system(s) are you seeing the problem on?

Windows 10.0.19045.0

bff3cd45-8d08-475a-b64e-849966501add

[rwkay]

sprite_delete returns a true (1) or false (0) value depending on if anything was actually deleted... if the sprite index is out of range or the sprite has previously been deleted then the return will be false (0), if something has been deleted then it will return true (1)

We should update the manual to reflect this.

[stuckie]

Will need to update GMLSpec as well.

[mgeddesGM]

verified with latest beta version of manual