Official Global Variable Names for San Andreas

[OrionSR]

Is there any interest in updating SB's custom variable lists for San Andreas? I just finished filling in the data for an updated version of the spreadsheet I've been maintaining to assist with save editing and script porting across various versions of San Andreas.

GTASA Global Translation Table 2022

This Google Sheet uses data from the variable-info output file from the leaked cs.exe compiler to lookup as-is variable names and variable type data mined from the source text to populate the variable table. Data for all classic versions are based on sergeanur's Undefinified Grove project, and should be as accurate as his reproduced scripts; the PCv1 version was spot on.

Variable lists for mobile, Xbox360 and PS3 were created by adjusting mock data from DE, a main.sc consisting of only variable declarations, to generate data for the Remastered versions based on prior research.

Version specific sheets include columns to produce CustomVariable.ini and CustomArray.ini files in Sanny's format.

• The complete list adds roughly 75KB to the size of compiled cleo scripts that include extra SCM info.
• Custom arrays for text labels have double-sized array declarations so Sanny will number all array elements properly.
• All arrays except the few single element custom arrays are declared as CustomArrays even if SB can identify them anyway. The extra declarations don't seem to cause any issue.
• Undefined global variable names created by users are compiled to unnamed array elements, which defeated the primary goal of naming all variables to push undeclared var names into the extended var space where they can't do any permanent damage.

[x87]

Hey 👋

Yes, definitely, these names would be a great addition. I think they suit GTA SA SCR mode better, also providing less breakage with existing scripts mostly written in SA PC 1.0 mode.

The complete list adds roughly 75KB to the size of compiled cleo scripts that include extra SCM info

this is not good. Not sure if we have to include the entire list, probably just those that are used in script would suffice.

Undefined global variable names created by users are compiled to unnamed array elements

🤔 so you want compiler to reserve array space even if it is not in use in the script, like regular variables? I thought it was already done like that

[OrionSR]

I had an idea for implementing an official variable table that might solve a number of issues:

Keep the functionality and contents of CustomVariables and CustomArrays the same as it's always been to maintain compatibility with previous scripts and strategies.

Implement a new Use Variable Table formatting option at a lower priority than the optional Custom overrides. Don't store the var table in Extra Info to avoid bloating the compiled scripts.

Use the same variable declaration format as used in the source scripts; type varname[arraysize]. The //main.sc column of the SA mobile sheet would be a simple, single-line example of VariableTable.ini.

Sanny could implement the type declarations of the variable table in a manner similar to a var..end construct. Given the suggested format, users would probably expect the type declarations to do more than just establish the sizes of arrays. Actually, it was the idea of generating a large #include file for global types, and bloating Extra Info even more, that led to the idea of a lower level implementation using the source script format.

so you want compiler to reserve array space even if it is not in use in the script, like regular variables? I thought it was already done like that

Ah! CustomArrays have no context/application(?) within a cleo script. Everything seemed to work as expected in SCM.

An awkward test of a user created variable name put it in the traffic cone array. This is a particularly problematic array as the driving schools will try to delete any SCM objects with handles that match values in the later part of the array, depending on how many cones are used to display the first lesson - example, the blackboard glitch. After traffic cones are girlfriend arrays - oh no! After $OnMission are the coords for the Catalina missions. (All that effort just to make the save corruption worse.)

It would probably be best to take a wider view and consider how variable tables might be used in a DE style, multi-file compiler.

[x87]

Can you attach here CustomVariables.ini and CustomArrays.ini?

[OrionSR]

For GTASA PC, either version. sa_Custom.zip CustomVariables.ini and CustomArrays.ini for other versions can be quickly copied from the columns of the version specific sheets. Filter out the blanks on the array column.

BTW, here's a link to the variable-info file I've been referencing for DE. I hacked the output string in my compiler to produce more favorable output, but this version contains the original glitch of a missing comma for global vars. It might be possible to import this data for use in Sanny. https://cdn.discordapp.com/attachments/363649662307270657/996512391095398571/variable_info.txt

[x87]

not sure what is the glitch but I added comma for global variables

variable_info.txt

[OrionSR]

Thanks. The glitch is in the printf formatting string in the compiler. I added in the comma and stripped the braces in serge's undefinified version of the compiler, but didn't think it fair to show the modified output in context to an import feature.

There doesn't seem to be any way to glean integer or float type from variable-info, but it should be possible to discover the text labels based on size of the array and offset of the next variable. Thing is though, the work has already been done for globals. A more interesting question would be, can Sanny make use of the local variable definitions?

[x87]

local variable definitions?

you mean, make local variables have names instead of indexes like 1@, 2@? How do I know which name a variable has?

[OrionSR]

There seems to be some weirdness in the main script, probably due to the running script lvars, but otherwise...

    {"BBTHROW", "C", 1, 31, 1},
    {"BBALL_CHAL", "BBHOOP", 1, 0, 1},
    {"BBALL_CHAL", "LOCATION_BLIP", 1, 1, 1},
    {"BBALL_CHAL", "X2", 1, 2, 1},
    {"BBALL_CHAL", "Y2", 1, 3, 1},
    {"BBALL_CHAL", "Z2", 1, 4, 1},

Name of script, Name of lvar, Array count, Lvar index, Use count.

Here's an example of an array of local shorts. The index of the following lvar identifies the length of the lvars.

    {"INTRO", "SUBTITLE_LABEL_CUT", 25, 95, 1},
    {"INTRO", "BIKE_EXISTS_CUT", 1, 145, 1},

[x87]

Would be nice to have a map between file names (e.g. BBALL_CHAL.sc) and script names in the main.scm ('BBCHAL'), since only the latter are available in the compiled scm.

[OrionSR]

That sounds... suspiciously promising. Really? You think you can pull this off? I'll see what I can do about mapping script names to filenames. Maybe someone's done this already.

More problematic would be extracting As-iS lvar names. The local list is considerably longer. But there's probably a good matching algorithm, I just don't know what it is. As for type information, any chance these compilers (DE vs Serge's UnDE) can be patched to;

• Maintain As-iS variable names
• Output variable type ID instead use info
• Swap the order of global output so var name is before script name (not sure how to key locals yet)

[OrionSR]

Different thought; something to think about as you're poking around with variables.

It's difficult to learn the global variable number of a custom variable without decompiling with customs disabled. Named globals don't offer the same sort of hint text as constants and model IDs. A tool that could cycle through $2, $player1 and $player_char might improve the user's experience with such a major change in how global variables are managed.

I haven't looked at named locals yet. Maybe the same thing applies.

[x87]

Not promising anything yet, I need to take a closer look at those files first. But I'm sure this info will be used eventually.

Re: patching compilers, I haven't looked at them, so better ask someone who already had.

[OrionSR]

Well... Fortunately, naming all of the local variables has never been a personal goal.

I was able to put together a quick script map fairly quickly using data I had already collected. There are still lots of gaps for scripts that didn't declare any global variables, but I should be able to fill those in quickly enough. In the meantime, the current list is somewhat useable. Vars Work Sheet

[OrionSR]

That was fun. I think I may have overdone it a bit, but it's nice when the data falls neatly in place. Same file as above but with a new name:

GTASA Script Map

Script Map sheet includes;

• an SCM sorted list of script and associated files
• different script names for PCv1 and DE; file names appear to be consistent.
• As-iS script names from DE, since that was the list I started with
• relative file paths, since I've been struggling to track down the correct file
• data maintained from SB, like mission/script numbers and descriptive text
• hyperlinks to UnDE files, because... overkill

The Files Paths Links sheet is sorted alphanumerically by directory. It's mostly used to generate the paths and links but includes references for which files are unused.

[x87]

Original names are now part of the SA SBL mode. https://github.com/sannybuilder/data/blob/0311f87ae7dc2af0d9d94d876b81b6d03e52f8fb/sa_sbl/CustomVariables.ini

with 3 exceptions:

• player_char
• player_actor
• onmission

[x87]

Closing as implemented in 4.0.0