Script reference improvements

[CharlesFolz4]

In events, scripts can be referenced in events via a numeric script ID
In scripts, external scripts can be referenced via CallCommonScript with a numeric script ID
Init scripts can also reference a ScriptID via InitScriptGoToIfEqual
In C code, scripts can be referenced by calling ScriptManager_Change() with a numeric script ID
These script IDs get converted into a numeric ScriptEntry offset via ScriptContext_LoadAndOffsetID()

Both the script IDs and the ScriptEntry offsets are magic numbers that are not very readable. Translating them into the label of the script that is being called is inconvenient, finding all references is annoying. The manual process of doing this is potentially and unnecessarily error-prone for the user.
A json entry of "script": 2027 is not very readable, nor is a script line of CallCommonScript 0x7FC.

This issue has been run into and initially discussed in #688 and #690. An initial solution was discussed, and it was decided that instead of slotting in a solution that worked for that one case, a more comprehensive solution was preferred. Ideally, there should be some consistent way of linking the scriptID, the ScriptEntry offset, and the name of the label, in some sort of unified value that is consistent, readable, and easily searchable.

So far, the only proposal for this was put forwards by @metallicity here.

[metallicity]

There was some feedback for the linked proposal on discord, where it was suggested using $CommonScript_SomeName: as a label (for every kind of ScriptEntry) seemed to be a decent alternative to new macros, as it'd be a valid label but not a valid C identifier. This still requires having source files be identified as "map vs. common", "local vs. external" or however else we might want to refer to them, and having their constants either be local indexes or global IDs which include their script offset, but simplifies the changes in individual source files. Given that the regex \bCommonScript_SomeName\b will still match a label prefixed by $, it's definitely possible to still find all constants for find/replace renaming, though it's admittedly also quite possible some regexes that previously would have matched will no longer do so.

Copying the relevant discord messages, so no one has to dig for them:

lhea said:

Some thoughts while reading through this:

1. I'm not certain how valuable moving files to a separate directory might be, as opposed to just modifying the name somehow. But I do think that it would be good to be clear about which files support external callers; I don't think we need to clarify local-only scripts, as that'd be a lot of unnecessary information overload. Assume local unless specified external.
2. Are we certain that we need to amend ScriptEntry to take a constant? I think that this will create more overall confusion. Could we instead make use of features built into the assembler for labels? Of note, symbol names are permitted to begin with any letter, ., or _. I don't know for sure if our machine-target supports $, but it may. We may also be able to use :: as a label prefix to denote that a label should be externally visible. I would rather we use something to this effect to make that distinction, if ScriptEntry itself is insufficient.
3. I think ScriptLabel as proposed here would probably be better defined as External or something similar to make it clear what it does. That said, I'm not a huge fan of generating labels from assembler macro-replacements. It feels a bit like code-smell.

cbt said:

We may also be able to use :: as a label prefix to denote that a label should be externally visible

i don't have a lot of time at this point to go through this + above linked document in whole, but just wanted to point out above sentence - the visual distinction between : and :: is very subtle and will likely be source of confusion for modders, if we rely on that to denote public vs private labels

metallicity said:

I had assumed there was zero overlap between "prefixes that we can safely use for labels here" and "prefixes that aren't technically some other valid C identifier". Most these suggestions either fail to build entirely (anything with ::) or with the constant included (e.g., .Common_HandleSignpostInput), but surprisingly enough $Common_HandleSignpostInput works just fine. So that sounds like it could be a cleaner way forward to me, if we want to just keep ScriptEntry taking a label.

We could also do something more explicit like External$Common_HandleSignpostInput (which also builds just fine), to address the point above.