Basics¶

In a Nutshell¶

Nutshell is designed to be a remarkably simple, lightweight game engine.

This page covers the foundational knowledge required to set up, run, and develop games using the framework.

Scripting¶

Squirrel¶

At its core, Nutshell is powered by a Squirrel virtual machine, which interprets scripts to drive your game.

This means you will need a basic grasp of the Squirrel programming language. If you are already comfortable with languages like C, C++, Java, Python, or Lua, you will find its syntax and dynamic object-oriented structure highly intuitive. Developers coming from environments like Godot (GDScript) or LÖVE (Lua) will feel right at home.

For a quick look at how straightforward it is to use, check out our Quick Start guide.

Useful Resources for Learning Squirrel:

• Squirrel - The programming language
• Squirrel 3.2 - Reference Manual
• Squirrel 3.2 - Standard Library

main.nut¶

Every Nutshell project MUST include a main.nut file at its root, serving as the primary entry point.

When you execute the nutshell binary, it automatically searches for this script in your current working directory.

update(dt) function¶

Every game MUST define an update(dt) function within the Squirrel root table.

• Purpose: This is where you implement simulation logic (calculating physics, updating character positions, handling NPC, processing triggers).
• Execution Rate: It is strictly invoked at a fixed rate of 60 times per second.
• Delta Time (dt): The dt parameter represents a stable, fixed time step of exactly 1/60^th of a second.

draw() function¶

Most games will also define a global draw() function in the root table.

• Purpose: This is dedicated exclusively to rendering your visuals (drawing text, geometric shapes, and image textures based on state data calculated in your update loop).
• Execution Rate: Unlike the fixed update loop, Nutshell dynamically calls draw() to match the native refresh rate of the monitor displaying the window.

Basic main.nut Skeleton¶

The most basic skeleton structure for your main.nut looks like this:

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

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

Managing Game Elements¶

Once your core main.nut file is established, you can begin utilizing the engine's built-in sub-systems.

Game Window¶

By default, Nutshell initializes a non-resizable window titled "nutshell" with an internal viewport resolution of 640x480 pixels. Window decorations (borders, titles, and system buttons) are drawn around these dimensions.

You can change these options at runtime by grabbing a reference to the window via Window.active() and calling the corresponding functions in the Window API (e.g., window.set_title("My Game")).

The active window area is referred to as the Canvas. Everything drawn by your scripts renders directly onto this canvas.

Game input¶

When the game window is actively focused, you can query hardware states using the Input API. It features comprehensive support for checking the status of the keyboard, mouse and gamepads.

Game assets¶

Asset paths are relative to the main.nut script.

Given a typical project layout:

.
├── audio
│   ├── crunch.ogg
│   └── background-theme.mp3
├── images
│   ├── acorn.png
│   ├── forest.png
│   └── squirrel.png
└── main.nut

You can reference the acorn sprite in your script using the relative path images/acorn.png.

Rendering Graphics & Text¶

• Geometry: Use the Canvas API to draw low-level geometric primitives (lines, rectangles, polygons, circles) directly onto the canvas.
• Sprites/Textures: Load static graphics via the Image API and draw them to the canvas using image.draw().
• Typography: Load font typography using the Font API and display text via font.draw().

Audio Playback¶

To add audio to your game, use the Audio API. You can stream immersive background music globally via Audio.bgm_play() or fire localized instant sound effects using audio.play().

Thats it?¶

Yes, that is the core workflow! The classes built into the Nutshell Standard Library expose everything required to build your game. When it doubt, C4^W reference it!