Getting Started

Getting Started

SQ# (SQF Sharp) is a modernized, embeddable reimplementation of Arma 3's SQF scripting language for .NET 10. Bring SQF scripting to any .NET project — game engines, tools, servers, or CLI apps.

What SQ# Is

• Scripting language — SQF-compatible syntax with modern enhancements
• Bytecode compiler — lexer, Pratt parser, stack VM
• Cooperative scheduler — lightweight fibers, multi-scheduler architecture
• Standard library — 100+ commands covering math, strings, arrays, types
• Embeddable — NuGet packages for any .NET 10 project

What SQ# Is NOT

• Game engine (no rendering, physics, audio)
• Network layer (UDP/TCP is host responsibility)
• UI system (no dialogs, displays, controls)
• Object system (vehicles, units — host defines these)

Installation

# Clone the repository
git clone https://github.com/ffredyk/SQF.NET
cd SQF.NET

# Build (.NET 10 required)
dotnet build

# Run tests
dotnet test

NuGet Packages

Package	Purpose
SQSharp.Core	SqValue, SqArray, bytecode types
SQSharp.VM	Stack VM + runtime
SQSharp.Compiler	Lexer + parser + bytecode compiler
SQSharp.Scheduler	Fiber scheduler
SQSharp.Host	High-level host API + 100+ StdLib commands
SQSharp.CLI	Command-line tool (dotnet sqf)

Most apps only need SQSharp.Host:

dotnet add package SQSharp.Hosting

Quick Start

CLI

# Run a script
dotnet run --project src/SQSharp.CLI -- run samples/basics.sqf

# Open interactive REPL
dotnet run --project src/SQSharp.CLI -- repl

# Compile to binary .sqfc
dotnet run --project src/SQSharp.CLI -- compile script.sqf --binary -o script.sqfc

C# Host

using SQSharp.Host;

var host = new SqHost();
host.OnPrint += msg => Console.WriteLine(msg);

host.ExecuteString(@"
    _arr = [1, 2, 3, 4, 5];
    _arr pushBack 6;
    print f'Array has {count _arr} elements';
");

host.TickMain();  // pump scheduler (in your game loop)

First Script

// hello.sqf
private _name = "World";
private _greeting = f"Hello {_name}!";
print _greeting;

// Variables and arithmetic
private _x = 10;
private _y = _x * 3 + 5;       // 35

// Arrays
private _arr = [1, 2, 3];
_arr pushBack 4;
private _len = count _arr;      // 4

// Control flow
if (_len > 3) {
    print "Array is long enough";
};

// Iteration
_arr forEach {
    print f"Element {_forEachIndex}: {_x}";
};

Architecture Overview

flowchart TB
    subgraph Host["HOST APPLICATION"]
        subgraph SqHost["SqHost (Host API)"]
            CmdReg["Command registration"]
            ScrEx["Script execution"]
            SchedMgmt["Scheduler management"]
            OutHdl["Output handling"]
        end
        SqHost --> Compiler["SQ# Compiler Pipeline<br/>Source Text → Lexer → Parser → Bytecode Compiler"]
        Compiler --> VM["Stack VM<br/>Bytecode execution · Fiber management<br/>Error handling · Stack traces"]
        VM --> Scheduler["Scheduler Layer<br/>Fiber scheduling · Time budget enforcement<br/>Multi-scheduler · Ownership tracking"]
    end

Loading

Compiler Pipeline

1. Lexer (SQSharp.Language.Lexer) — Source text → token stream. Handles keywords, identifiers, operators, literals, comments.
2. Parser (SQSharp.Language.Parser) — Tokens → AST. Pratt parser with 11 precedence levels. Handles control flow constructs (if, while, for, switch, try/catch).
3. Compiler (SQSharp.Compiler.Compiler) — AST → bytecode (BytecodeChunk). Constant folding, short-circuit optimization, params inlining.

VM

The stack VM (SQSharp.VM.SqVm) executes bytecode instructions:

• Stack-based architecture (push/pop operands)
• ~40 opcodes (OpCode enum)
• Fiber-aware execution (yield/resume)
• Error stack traces with source locations

Scheduler

Each SqScheduler manages:

• Ready queue — fibers waiting to run (FIFO)
• Waiting list — fibers in sleep or await
• Time budget — configurable ms per Tick() (default 3ms)
• Ownership — tracks which scheduler owns each mutable value

Version

v0.7 — Language complete. All core features working. 122+ tests passing.

See Also

• Language Guide — syntax, variables, operators, precedence
• Type System — all types, nil/nothing/void
• Commands — full command reference (100+ commands)
• Host API & Embedding — C# integration guide
• Concurrency & Multithreading — schedulers, fibers, thread safety