Local Variable Space Extension & Virtual Variables RFC

[x87]

Goal

• Increase variable limit in CLEO scripts for advanced scripting
• Get easy access to some data that is normally available via Global variables or Memory addresses

Scope

• Initial phase: GTA SA.
  • Eventually can be ported to III/VC
• Does not affect functionality of main.scm scripts and missions

Glossary

• LVI - local variable index. Index 0 through 31 in the static array pre-allocated for each script. 32 and 33 are built-in timers.

Design

• Allow LVI beyond 33@
• Make LVI a signed 16 bit integer (-32,768 to +32,767)
• LVI 0-33 act like normal variables and store their data in the script struct
• LVI 34-32,767 store their values in the static buffer allocated by the compiler in a custom CLEO header
  • compiler identifies the highest LVI and allocates just enough space for variables in the current script (similar to global varspace in main.scm)
• Negative LVI are virtual variables, they point to a specific memory location
  • -1 is a pointer to ONMISSION variable
  • -2 is a pointer to current script struct
  • more virtual variables can be added if needed

Runtime support

CLEO should provide new implementation for

• CRunningScript::CollectParameters
• CRunningScript::StoreParameters
• CRunningScript::GetPointerToLocalVariable
• CRunningScript::GetPointerToLocalArrayElement

Compiler support

• Compiler should preallocate local varspace in the custom header
• Ranges check should be lifted
• Virtual variables should be defined as constants (e.g. const ONMISSION = -1@)

Backward compatibility

• Old scripts using standard LVI will produce expected results with the new version of CLEO.
• Scripts using non-standard LVI will not produce expected results with older versions of CLEO 4.