Sverchok Syntax Scripting

sverchok-syntax-scripting

Quick Reference

Script Node Overview

Sverchok provides 4 primary scripting nodes for embedding custom Python logic in node trees:

Critical Warnings

NEVER use import os, import subprocess, or file-system operations inside Formula Mk5 — the safe_eval system blocks all builtins and ONLY allows whitelisted functions.

NEVER store mutable state in SNLite script-body variables across evaluations — use get_user_dict() for persistent per-node storage.

NEVER define sockets manually in SNLite (via self.inputs.new(...)) — ALWAYS use the text-based declaration syntax in the docstring header.

ALWAYS wrap SNLite output data in the correct nesting level — verts = [[(x,y,z), ...]] not verts = [(x,y,z), ...].

ALWAYS use functor_init() (not __init__) to create sockets in SN Functor B scripts.

ALWAYS end Profile Mk3 H and V commands with a semicolon ;.

Decision Tree

Need custom Python logic in a node tree?
├── Quick prototype / simple transform → SNLite
├── Need custom UI + multiple properties → SN Functor B
├── Math expression only (no logic) → Formula Mk5
└── 2D parametric shape / architectural profile → Profile Mk3

Writing an SNLite script?
├── Need persistent storage → get_user_dict()
├── Need one-time init → setup() function
├── Need custom UI → ui(self, context, layout) function
├── Need BMesh operations → bmesh_from_pydata / pydata_from_bmesh aliases
└── Need NumPy performance → np alias (pre-imported)

Choosing SNLite vs Functor B?
├── Simple I/O, few properties → SNLite
├── Need > 2 enums or typed properties → Functor B (5x int/float/bool)
├── Need full self access in process() → Functor B
└── Learning / quick iteration → SNLite

SNLite: Socket Declaration Syntax

Declaration Format

Socket declarations go in the script's opening docstring:

"""
in  socket_name  type  [default=value]  [nested=level]  [required=True]
out socket_name  type
"""

Socket Type Identifiers

Declaration Options

Built-in Aliases

These names are pre-imported and available in every SNLite script:

vectorize           # sverchok.utils.snlite_utils — auto-vectorize functions
bpy                 # Blender Python API
np                  # NumPy
bmesh_from_pydata   # Build BMesh from verts/edges/faces lists
pydata_from_bmesh   # Extract verts/edges/faces from BMesh
get_user_dict       # Persistent per-node dict storage
reset_user_dict     # Clear per-node storage (hard=True clears all)
cprint              # Console output (alias: console_print)
ddir                # Filtered dir() utility
sv_njit             # Numba JIT compilation wrapper
sv_njit_clear       # Clear Numba JIT cache

Special Functions

setup() — Runs once on script load. Return values persist via return locals():

def setup():
    import random
    seed_data = [random.random() for _ in range(100)]
    return locals()
# seed_data is now available in the main script body

ui(self, context, layout) — Custom node panel UI:

def ui(self, context, layout):
    layout.label(text="My Custom Node")
    layout.prop(self, "custom_enum")

sv_internal_links(self) — Controls pass-through when node is muted:

def sv_internal_links(self):
    return [(self.inputs[0], self.outputs[0])]

Additional Features

Custom enums (maximum 2 per script):

"""
enum mode = Add Subtract Multiply
in  value s  default=1.0
out result s
"""
if mode == "Add":
    result = [[v + 1 for v in value]]

File handler — adds a text datablock selector to the UI:

"""
display_file_handler
in  scale s  default=1.0
out verts v
"""

Includes — import other Blender text datablocks:

"""
includes: helper_functions.py, config.py
in  data s
out result s
"""

Persistent storage via get_user_dict():

"""
in  trigger s  default=0
out count   s
"""
storage = get_user_dict()
if 'counter' not in storage:
    storage['counter'] = 0
storage['counter'] += 1
count = [[storage['counter']]]

Template System

SNLite templates are located in node_scripts/SNLite_templates/ with categories:

SN Functor B: Structured Scripting

Three-Function Architecture

import bpy
from sverchok.data_structure import updateNode

def functor_init(self, context):
    """Called once when script is loaded. Define sockets here."""
    self.inputs.new('SvStringsSocket', 'radius')
    self.inputs.new('SvStringsSocket', 'segments')
    self.outputs.new('SvVerticesSocket', 'verts')
    self.outputs.new('SvStringsSocket', 'edges')

def process(self):
    """Called on each evaluation. Read inputs, write outputs."""
    if not self.inputs['radius'].is_linked:
        return
    radius_data = self.inputs['radius'].sv_get()
    # ... processing logic ...
    self.outputs['verts'].sv_set(all_verts)

def draw_buttons(self, context, layout):
    """Optional custom UI in the node body."""
    layout.prop(self, 'float_00', text='Scale')
    layout.prop(self, 'int_00', text='Count')

Pre-defined Properties

Functor B provides 15 pre-defined properties (5 of each type), all with update=updateNode:

Access in draw_buttons: layout.prop(self, 'float_00', text='My Label') Access in process: scale = self.float_00

SNLite vs Functor B

Formula Mk5: Expression Evaluation

Basic Usage

The Formula node evaluates Python math expressions with safety restrictions. Supports 4 simultaneous formulas. Variables in expressions automatically become input sockets.

Formula 1: x + 1
Formula 2: R * sin(phi)
Formula 3: 0.75 * X + 0.25 * Y
Formula 4: [v**2 for v in range(n)]

Safe Evaluation Environment

The safe_eval() system blocks ALL Python builtins and ONLY allows:

Math functions: acos, acosh, asin, asinh, atan, atan2, atanh, ceil, copysign, cos, cosh, degrees, erf, erfc, exp, expm1, fabs, factorial, floor, fmod, frexp, fsum, gamma, hypot, isfinite, isinf, isnan, ldexp, lgamma, log, log10, log1p, log2, modf, pow, radians, sin, sinh, sqrt, tan, tanh, trunc

Constants: pi, e

Utility functions: abs, sign, max, min, len, sum, zip, any, all, dir

Type constructors: int, float, str, list, tuple, dict, set

Objects: Vector, Matrix, np (NumPy), bpy

Output Configuration

NumPy Mode

When enabled, math functions use NumPy array variants (sin → np.sin), enabling vectorized computation on arrays instead of scalar-by-scalar evaluation.

Profile Mk3: SVG-like 2D Profiles

DSL Command Reference

Variable System

default width = 0.3          # Becomes input socket with default value
default height = 2.7         # Becomes input socket with default value
let half_width = {width / 2} # Computed variable, does NOT become socket
let ft = {flange_thickness}  # Reusable shorthand

M -{half_width} 0            # Use variables in commands
L {width + margin} {height}  # Expressions in curly braces

• default variables become input sockets (auto-created)
• let variables are computed internally — NEVER become sockets
• Expressions use {curly braces} for inline math
• close_threshold property (default 0.0005) detects overlapping start/end vertices

Architectural Profile Example: I-Beam

default width = 0.2
default height = 0.4
default flange_thickness = 0.02
default web_thickness = 0.01

let hw = {width / 2}
let hh = {height / 2}
let ft = {flange_thickness}
let wt = {web_thickness / 2}

M -{hw} -{hh}
L {hw} -{hh}
L {hw} {-hh + ft}
L {wt} {-hh + ft}
L {wt} {hh - ft}
L {hw} {hh - ft}
L {hw} {hh}
L -{hw} {hh}
L -{hw} {hh - ft}
L -{wt} {hh - ft}
L -{wt} {-hh + ft}
L -{hw} {-hh + ft}
X

Other Script Nodes

Reference Links

• references/methods.md — API signatures for SNLite, Functor B, Formula Mk5, Profile Mk3
• references/examples.md — Working code examples for each scripting node
• references/anti-patterns.md — Common mistakes and WHY they fail

Official Sources

• https://github.com/nortikin/sverchok/blob/master/nodes/script/script1_lite.py
• https://github.com/nortikin/sverchok/blob/master/nodes/script/sn_functor_b.py
• https://github.com/nortikin/sverchok/blob/master/nodes/script/formula_mk5.py
• https://github.com/nortikin/sverchok/blob/master/nodes/script/profile_mk3.py
• https://sverchok.readthedocs.io/