Advanced Usage¶

Ghost in a Nutshell¶

Welcome to the advanced documentation of Nutshell.

While the basic framework handles straightforward, single-window games, scaling a project requires mastering the underlying runtime environment.

Scripts & Asset Management¶

Path Management¶

When loading an image, loading an audio file, or requiring external scripts, file paths are resolved by Nutshell using specific rules.

Let's assume your project uses the following directory structure:

/path/to/my/game
├── main.nut
├── audio
│   ├── crunch.ogg
│   └── background-theme.mp3
├── images
│   ├── acorn.png
│   ├── forest.png
│   └── squirrel.png
└── src
    ├── draw.nut
    └── update.nut

Relative paths¶

By default, assets are resolved via a path relative to the script that executes the load call.

Absolute paths¶

You can also use system-specific absolute paths to target files anywhere on the host machine.

local sampleFont = Font("/usr/share/fonts/truetype/noto/NotoSansArabic-Regular.ttf");
sampleFont.draw(10, 10, "مرحبا بالعالم")

Project Root & Resource Paths (res://)¶

The Project Root is explicitly defined as the directory containing your game's entry point, main.nut.

To reference files from anywhere in your codebase without writing complex relative paths, you can use a Resource Path. A resource path bypasses the current script's location and evaluates paths relative to the project root using the res:// prefix.

This approach is highly recommended because it prevents broken paths if you decide to reorganize or move scripts into different subfolders later.

Dynamic Resolution: System.script_path()¶

While relative tracks and the res:// protocol handle the vast majority of asset loading use cases, you may occasionally need to inspect or dynamically manipulate paths at runtime—especially when writing reusable plugins, shared libraries, or advanced logging tools.

The System.script_path() static method returns a string containing the full filesystem path of the currently executing script file.

The simplest and most common use case for this is loading adjacent data configurations. If you separate your game logic into isolated modules (like an achievement manager or an enemy spawner), you often want that script's data files to live in the exact same folder so everything stays organized.

// Inside src/entities/enemy.nut
local currentScript = System.script_path();

local lastSlashIdx = -1;
local searchIdx = currentScript.find("/");

// Keep finding the next slash until find() returns null
while (searchIdx != null) {
    lastSlashIdx = searchIdx;
    searchIdx = currentScript.find("/", searchIdx + 1);
}

if (lastSlashIdx != -1) {
    local folderPath = currentScript.slice(0, lastSlashIdx);
    local dataPath = folderPath + "/enemy_stats.json";

    print("Loading stats from: " + dataPath);
}

Script Modularization with require(path)¶

The require(path) utility allows you to modularize your code by loading and executing external scripts from within your current script.

This function is registered globally within the Squirrel root table of the active virtual machine. You can use it to keep your codebase clean, decoupled, and scaling beyond a single main.nut file:

// Split game states out into dedicated sub-scripts
require("src/update.nut")
require("src/draw.nut")

function update(dt) {
    // Process game logic and state changes here
}

function draw() {
    // Render visual elements here
    Font("").draw(10, 10, "Hello Nutshell!")
}

Multi-Virtual Machine Architecture¶

By default, Nutshell initializes and runs a single virtual machine. However, you can spawn and run multiple independent virtual machines simultaneously using the System API.

Inter-VM Communication¶

At the moment, you can't share data between two virtual machines.

The only actions you can take in a virtual machine is either to spawn or kill another virtual machine by its identifier.

Multi-Window Management¶

Nutshell supports multiple windows. You can spawn and configure multiple concurrent game windows using the Window API.

Contextual Limitations¶

A disclaimer though:

Active Window¶

An active window is where all current canvas drawing operations are actively directed.

• To get the active window reference: Window.active().
• To bind drawing operations to a specific window: window.activate().

Focused Window¶

A focused window is the one currently intercepting active OS hardware mouse, keyboard, or controller inputs.

• To get the currently focused window: Window.focused_id().
• To check if a window instance has the focus: window.focused().
• To forcefully request focus for a specific window: window.focus().

Automatic Windows¶

By default, Nutshell automatically instantiates a new window with default dimensions whenever a new virtual machine is initialized.

You can pass the following command-line flags to the nutshell binary to alter or override this automatic window behavior:

Security Considerations¶