Follow-up to #4602. Overall the PR was good, but there are a few extra small changes that should go in. In order of priority:
1) The `exitLoop`, `skipMission`, and `skipTraining` functions should check for campaign mode.
2) The `isVisible` virtvar should be changed to a function, because calling it may have side effects. In standard usage, the briefing formula is evaluated exactly once per stage on briefing initialization, so scripts should follow this convention.
3) The `hasGoalsSlide` function should be called `hasGoalsStage`, because "stage" is the common terminology in FSO.
4) Paging out mission messages is already done in `game_level_close` and should be removed from not only the scripting method but the method it was based on.
5) For consistency, unused parameters should use the `SCP_UNUSED` macro.
6) The `isTraining` flag check can be slightly streamlined using the double-not trick.
This allows to mark certain functions or virtvars to be declared as
"deprecated" starting with a specific engine version. What this means is
that a special message will be added to the documentation stating since
when the function is deprecated and can contain an optional message. The
actual enforcement of the deprecation depends on the target version of
the mod so that we can stay backwards compatible.
If the mod supports the version since when the function is deprecated,
it will not be added to the Lua state which means that it doesn't exist
for the calling script. If the targetted version is before the stated
version, the function will still be added to the Lua state.
As the first function to use this feature, I have deprecated
createParticle in the testing library and moved it to the graphics
library with a new name reflecting that it creates a persistent
particle. I also added the corresponding function for adding a
non-persistent particle.
This will automatically call the destructor of a type of Lua calls the
garbage collector for an object of that type. This is the last step
towards fully supporting non-trivial objects in the Lua API and all
previous workarounds have been removed.
This maintains the type information which can be used for enforce
const-correctness and also for implementing more advanced ways of
handling the type information.
The current particle system uses dynamic allocation of particle
instances for keeping track of particle instances. This adds unnecessary
overhead in case the code does not need a handle to this particle which
is the case in pretty much all instances.
The new non-persistent particles are stored in a standard vector without
dynamic allocation which should make the processing steps using this
vector much faster and allow better scalability in case more particles
are used by a mission.
As described in #1278, the current scripting system has issues with
handling non-trivial C++ types. Since fixing that deficiency is too much
work, especially since we are in a feature freeze, I decided to simply
enforce the usage of trivial types for scripting handles. Fortunately,
only two handles used non-trivial types so it was relatively easy to fix
those instances by dynamically allocating those and only storing the
pointers in the lua memory.
This fixes a bug in JAD-XA where the game would crash at the last boss.
Also, I noticed that the HudGauge handle used a copy of the hud gauge
rather than a pointer to the actual instance so I'm pretty sure that any
scripting changes to a custom HUD gauge simply didn't work before.
Goober5000