Sanny Builder 4.0

I'm thrilled to announce the release of Sanny Builder 4.0, marking a significant milestone in the evolution of Sanny Builder.

This version brings in new language constructs such as functions and switch..end, improved interface, even better integration with Sanny Builder Library, and much much more.

It wouldn't be possible without great feedback, bug reports and support from the Sanny Builder community and my supporters here on Patreon. I'm extremely grateful to each one of you!

So let's take a look at some of the new features.

Functions 

This is by far the most important addition to the Sanny Builder language in many years. SCM does not support functions natively, so in order to reuse the code you need to resort to limited gosub routines or hacks like spawning child scripts with custom arguments.

CLEO expands the runtime and adds SCM functions to address this limitation. In CLEO 5 functions received even more improvements. Functions now maintain its own gosub stack and the condition flag, are able to operate with string arguments, and got a new return_with command. With all of this enhancements, using old plain opcodes to call the function in the source code felt archaic and awkward.

This is where new function declarations come into play. In SB4 you can define a function anywhere in the script and call it by name passing in the arguments and getting back the result(s). A function may look something like this:

function sum(a: int, b: int): int
    int result = a + b
    return result
end

It receives two integer arguments and returns back its sum. To call the function in the code use the following syntax:

int s = sum(100, 200)

and s will contain a number 300. To learn more about functions, read through the documentation.

Function syntax also covers so-called foreign functions, which are functions in the game code that you may call by the address. Previously you would use commands like CALL_FUNCTION, CALL_METHOD, CALL_FUNCTION_RETURN, etc. Now you can define the function and call it using the same familiar syntax:

function getCoords<cdecl, 0x0C000DE>(a: Car): float, float, float
...
float x, y, z
x, y, z = getCoords(myCar)

Scoped variables

This feature is naturally coupled with functions, because now any custom variable declared in a function only exists within this function. You can declare variables with the same name in different functions and they won't clash:

int state = 1
foo()
bar()
// state is still 1 after calling foo() and bar()

function foo()
    int state = 2
end

function bar()
    int state = 3
end

switch..end 

SB 4 supports switch..end in all games. Switch construct allows to execute different code based on the value of the variable. The syntax is simple:

int x = 5
switch x
    case 5
        print_formatted "x = 5" 250

    case 6
        print_formatted "x = 6" 250

    default
        print_formatted "x is something else" 250
end

Debugger

SB4 has a built-in debugger for SCM scripts. Currently it only supports debugging main.scm and not CLEO scripts. You can view a separate demo here.

In the current state the debugger allows pausing the game on a certain line of code, inspecting variables and stepping in one opcode at a time. Note that CLEO 5 has a similar functionality added in the DebugUtils plugin with breakpoint and trace commands, but they don't pause the whole game.

CLEO Modules 

SB4 allows creating CLEO Modules, which is another new feature in CLEO 5. CLEO Module is a compiled script that exports SCM functions. These functions can be imported and called from other scripts:

example module:

{$CLEO .s}
export function sum(a: int, b: int): int
    int result = a + b
    return result
end

example script:

import sum from "sum.s"
int s = sum(100, 200)

The example module should be compiled into sum.s file and put next to the script file in the script directory. CLEO 5 is responsible for linking the module code in runtime. Module authors have freedom to pick their favorite edit mode or even an alternative compiler to create and share their libraries.

New Edit Modes 

SB4 adds 3 new edit modes: GTA III SBL, GTA VC SBL and GTA SA SBL. They each use command definitions from Sanny Builder Library - a community-driven platform for documenting native commands and custom (CLEO) extensions. These definitions include enums, classes, types for all parameters. SBL website provides a download of the most recent classes.db and opcodes.txt files for the use with Sanny Builder. Additionally new modes use JSON file provided by SBL (gta3.json, vc.json, sa.json) as a replacement for corresponding legacy SCM.INI files.

With new edit modes your can use native command names as designed by Rockstar Games in addition to extensive class system grouping similar commands into namespaces. Commands related to the player can be found in the Player class, commands related to vehicles can be found in the Car class, commands related to people (gang members, special characters, pedestrians) can be found in the Char class, and so on.

Old legacy modes are deprecated and will not be supported. It is recommended to write any new script using the SBL modes. Refer to this document to find out key differences between old and new modes.

Tutorial 

New tutorial dedicated to new concepts of programming with Sanny Builder 4 has been started. Its goal is to teach scripting to newcomers using modern features. This tutorial is at very early stage, and will be kept updated. Any contributions are welcome.

There are many more big and small features not covered in this article, so please visit this GitHub ticket for the complete list and additional information. You are also welcome to join our vibrant Discord community. 

Sanny Builder 4 is the start of a new chapter and there is many more exciting stuff coming. Thank you for being part of this journey!