Godot Sandbox

The GDScript-to-RISC-V compiler performs optimizations on the Intermediate Representation (IR) before generating RISC-V code. These optimizations run in multiple iterative passes to reduce code size, eliminate redundancy, and improve runtime performance.

Optimization Pipeline Order:

1. Constant Folding (Enables downstream optimizations)
2. Copy Propagation (Basic cleanup)
3. Enhanced Copy Propagation (Advanced cleanup)
4. Loop-Invariant Code Motion (Hoist invariants)
5. Peephole Optimization (Local patterns)
6. Peephole Optimization (Second pass)
7. Redundant Store Elimination (Before dead code)
8. Peephole Optimization (Final cleanup)
9. Dead Code Elimination (Remove unused code)

Moves loop-invariant computations outside of loops to avoid redundant execution.

Limitations & Behavior:

• Nested Loops: Currently, the optimizer skips the entire function if any nested loops are detected to avoid hoisting past incorrect loop headers.
• Hoisting Criteria: Only hoists pure operations: LOAD_IMM, LOAD_FLOAT_IMM, LOAD_BOOL, LOAD_STRING, and MOVE.
• Safety Checks: Verifies the destination register is not read before definition and that source registers are not modified anywhere within the loop.
• Identification: Identifies loops via back edges (a JUMP to an earlier label).

Example:

while i < 10:  # "10" is loop-invariant
    i = i + 1  # "1" is loop-invariant

Applies pattern-based local optimizations on small instruction windows. Common patterns include:

• Eliminating self-moves (e.g., MOVE r0, r0).
• Collapsing move chains around operations.
• Removing redundant move pairs (e.g., MOVE r1, r0; MOVE r0, r1).
• Optimizing common patterns like count = count + 1.

Evaluates constant expressions at compile time instead of runtime. It handles integer and float arithmetic, supports comparison operations, respects GDScript type promotion (e.g., int + float $\rightarrow$ float), and avoids division by zero.

Example:

var x = 5 + 10  # Compiled as: x = 15
var y = 2.0 * 3.0  # Compiled as: y = 6.0

Godot Sandbox allows you to run C++, Rust, and SafeGDScript by compiling them into ELF resources. You can use these resources in two ways:

1. Using a Sandbox Node

Create a new Sandbox node in your scene and assign an ELF resource to it.

• The Sandbox node follows the standard Godot node lifecycle.
• You can use @export to provide auto-completion from other GDScripts.

2. Using ELF resources directly as scripts

You can directly assign an ELF script resource to a node.

• This uses a shared sandbox among all instances of that script, providing maximum scalability.
• You can call functions and attach signals just like standard GDScript.

A critical architectural detail for developers is that the current RISC-V codegen is entirely stack-based and ignores the sophisticated register allocator.

Current Behavior:

• All operations load Variants from the stack.
• Operations use only t0 as a scratch register.
• Results are stored back to the stack.

Implications:

• Even though a register allocator assigns 18 physical RISC-V registers (t0-t6, s1-s11), they are not utilized for data movement in the current implementation because the Variant ABI is complex (Variants are 24 bytes and system calls operate on Variant pointers).
• The main performance bottleneck is this stack-based approach rather than the IR optimizations themselves.

These optimizations eliminate redundant MOVE instructions.

• Copy Propagation: Eliminates redundant MOVE instructions after constant loads.
• Enhanced Copy Propagation: Tracks copy chains and propagates sources through uses. It follows chains to the original source and verifies the source register hasn't been modified. It clears tracking at control flow boundaries and handles special cases for BRANCH_ZERO/BRANCH_NOT_ZERO.

Example (Enhanced):

var a = x
var b = a
return b  # Can use x directly

Removes dead stores and consecutive identical stores. If a register is loaded with a value and then immediately overwritten by another load before being used, the first store is eliminated.

Example:

LOAD_IMM r0, 10
LOAD_IMM r0, 20  # First store is dead

Result:
LOAD_IMM r0, 20

This project uses a build.sh script to build RISC-V C and C++ programs with the Godot Sandbox API. The build process utilizes Zig to handle the compilation and linking. The resulting binaries are placed in a hidden .build directory.

# Example: Build with stripping enabled
$ ./build.sh --strip

To build Godot Sandbox as a native module within a Godot repository, add it as a submodule and initialize it:

git submodule add https://github.com/libriscv/godot-sandbox modules/sandbox
cd modules/sandbox
git submodule update --init --recursive