Script compilation - adventuregamestudio/ags GitHub Wiki

The AGS Script Compiler takes AGS Script and converts in bytecode that can be ran in the AGS script execution logic.

Whenever the Compiler works with Scripts or Headers, these are already preprocessed, meaning that macros and comments have already been successfully stripped from the resulting files.

The Compiler Execution

Currently, the compiler usage works through certain steps.

  1. It starts up with ccRemoveDefaultHeaders() to clean and set up the headers for usage.

  2. It then uses ccAddDefaultHeader() to pass Headers that should be considered for the script we are going to compile.

  3. Use ccSetSoftwareVersion() once, to set the Editor version.

  4. Applies ccSetOption() as many times as there are relevant options for it.

  5. Finally it runs ccCompileText() producing the output object we want.

The Compiler Output

The compiler generates the following data in a ccScript object:

  • globaldata : is an initialized block of memory where the global variables reside.

  • strings : is an initialized block of memory that contains all the concatenated string literals, separated by \0

  • code : is a chunk of Bytecode (ags machine code)

  • fixups : is an array of pointers into code. Each pointer declares that the respective address in code has to be patched by the linker in some way before it can be used. For instance, the respective address might be relative to strings, so when the linker has allocated the strings starting at some real memory address, it must add this real memory address to this respective address. Or as another example, the respective address might be relative to globaldata, so the linker must add the real memory address of the globaldata chunk to this respective address.

  • fixuptypes : is an array of bytes. The n-th byte of fixuptypes corresponds to the n-th pointer of fixups and specifies in what specific way the address in code must be modified. For instance, 3 means "this is relative to strings"; as another example, 1 means "this is relative to globaldata".

  • imports : is an array of C strings that specifies the names of those variables that will be read from other compiled modules

  • exports : is an array of C strings that declares the names of those variables that other modules can read

  • export_addr : is an array of pointers into globaldata. The n-th pointer of export_addr corresponds to the n-th C string of exports and specifies just where the bytes are that are exported.

  • sections : is an array that contains source file names. When the program is run and runtime errors happen, then this information will be used to point out just what source produced the runtime error.

Linking

Linking is done at runtime in the Engine, so there's no link step after compiling scripts.

Links