Jump to content
Setting up an AI agent? ReverseEngineering.wiki skill (works from the command line, no configuration): https://reverseengineering.wiki/skill/rewiki/SKILL.md · setup for every client, including MCP: https://reverseengineering.wiki/llms.txt · REWiki:Connect

Library:Squirrel

From ReverseEngineering.wiki
Library
Developer Alberto Demichelis
License MIT
Website http://www.squirrel-lang.org
On this wiki Facts · Code · Notes · Topics

Squirrel is a small C++ scripting language and VM (MIT license, Alberto Demichelis) embedded in many games and applications; its scripts ship as source (.nut) or compiled closures (.cnut).

Identification

  • Version strings in the binary: Squirrel 3.2 stable (SQUIRREL_VERSION) and Copyright (C) 2003-2024 Alberto Demichelis; earlier releases carry their own number in the same pattern. sq_getversion() returns SQUIRREL_VERSION_NUMBER (320 for 3.2).
  • Exports (when built as a DLL or kept in a symbol file) all start with sq_: sq_open, sq_newthread, sq_compilebuffer, sq_pushroottable, sq_call, sq_newclosure, sq_pushstring, sq_readclosure, sq_writeclosure, sq_getversion (149 SQUIRREL_API declarations in include/squirrel.h). The standard library adds sqstd_register_iolib, sqstd_dofile, sqstd_loadfile.
  • Runtime error strings help to find the VM: cannot serialize a %s, invalid stream, a closure with free variables bound cannot be serialized, io error.
  • A compiled script starts with the bytes FA FA 52 49 51 53: see Format:Squirrel bytecode.

Scripts in games

Games load .nut source or .cnut compiled closures through sq_compilebuffer / sq_readclosure from their own archives. Some engines wrap the buffer (XOR, compression) before loading: find the call to sq_readclosure or sq_compile and look at the buffer there. Unverified: some embedders patch the opcode set; if the header parses but instructions do not decode, compare the game's opcode table with squirrel/sqopcodes.h.

Code & repositories

  • https://github.com/albertodemichelis/squirrel @ f9267f2f2a9afa1face89d8ea078c686331e30d1 · license: MIT
    Reference Squirrel VM. Useful without running: squirrel/sqobject.cpp (closure save/load), sqopcodes.h (opcodes), include/squirrel.h (API, type constants).
    Tested on: source read, not run: source read, not run · checked 2026-10-18; last activity 2026-02-28

Pitfalls

  • The sizes of SQChar, SQInteger and SQFloat are in the stream header and differ between builds.
  • Debug info (line info, local names) is kept unless the game compiled with sq_enabledebuginfo(v, SQFalse).

See also

Library:Lua and Library:LuaJIT for the other common game scripting VMs; Library:QuickJS.