VibeGeometry/docs/research/geometry-script-fork-notes.md

Geometry Script Fork Notes

VibeGeometry uses a repo-local Geometry Script clone at:

external/geometry-script

The clone currently tracks upstream:

https://github.com/carson-katri/geometry-script.git

The GameCult fork remote is:

https://github.com/GameCult/geometry-script.git

The fork is intentionally kept small. As of 2026-05-04, its live branches are:

main
vibegeometry/blender-5-nested-tree-groups
vibegeometry/blender-5-nodes-to-script

Upstream may still have historical branches such as gh-pages or nodes_to_script; those are upstream history, not GameCult fork policy.

Upstream nodes_to_script Branch

Upstream's historical nodes_to_script branch is real and potentially useful, but should be treated as prototype material rather than a drop-in dependency.

Observed on 2026-05-04:

• Branch head: b78ec37 (Improve dot access handling, 2023-03-01).
• Merge base with current main: 5fbc7d1.
• Main has substantial later work not present on the branch, including Blender 4 NodeTree.interface migration, nested tree checks, repeat-zone support, and Blender 3/4 compatibility fixes.
• The branch adds operators/convert_tree.py and registers a geometry_script.convert_tree node editor operator.

The operator walks the active node tree, creates one assignment per node, reads enabled input defaults and node-specific properties, follows links into arguments, topologically sorts from Group Output, then writes a generated @tree(...) script into a Blender text datablock.

That makes it useful as a translation assistant or bootstrap oracle. It does not replace manual doctrine-building yet: output quality, Blender 5.1 compatibility, interface sockets, zones, nested groups, multi-input sockets, and current Geometry Script API drift all need testing before VibeGeometry leans on it.

Patch work belongs in this clone first, then in a fork branch/PR. Do not patch the installed AppData add-on directly. That path is live installation state, not source control, and it will quietly become a stupid little archaeological layer if indulged.

Setup

Run from the VibeGeometry repo root:

.\tools\setup_geometry_script_clone.ps1

This clones upstream into external/geometry-script, creates or switches to the current VibeGeometry toolchain branch, and applies the patches stored in:

patches/geometry-script/0001-fix-nested-tree-group-references-on-blender-4.patch
patches/geometry-script/0002-Port-node-tree-conversion-operator.patch
patches/geometry-script/0003-Tolerate-Blender-menu-socket-defaults.patch

external/ is intentionally ignored by the VibeGeometry repository. The clone is source-controlled as its own repo, not smuggled into this repo as a pile of vendor files.

Toolchain Branch

Branch:

vibegeometry/blender-5-nodes-to-script

This is the branch VibeGeometry should use locally. It contains:

• the nested @tree group fix from vibegeometry/blender-5-nested-tree-groups
• a Blender 5.1 port of the historical nodes_to_script converter prototype
• a Blender 5.1 menu-socket default tolerance fix so group construction does not fail when NodeSocketMenu enum items are not populated yet

The converter adds:

• operators/convert_tree.py
• a callable convert_node_tree(tree) function for headless tests
• a geometry_script.convert_tree node editor operator that writes a generated script into a Blender text datablock

Smoke test:

& 'C:\Program Files (x86)\Steam\steamapps\common\Blender\blender.exe' --background '.\experiments\source-blends\shriinivas-fieldvalue.blend' --python '.\tools\smoke_nodes_to_script_converter.py' -- --groups 'Create Decimal' 'Digit At' 'Next Digit' 'Seven Segments' 'Delete Segments' 'Field Value' --json '.\experiments\inspection\nodes-to-script-smoke.json' --out-dir '.\experiments\inspection\nodes-to-script-output'

Current acceptance:

• Converter runs in Blender 5.1.1.
• Generated drafts compile as Python for the tested groups.
• The full 176-node Field Value source group emits a 179-line draft script.
• Generated text is a bootstrap draft, not doctrine-quality final code or style guidance.

Known limits:

• Nested source group calls are emitted by source group name, so dependency groups must be converted or replaced by hand-authored equivalents.
• The generated script preserves node-level wiring and therefore can be noisy.
• Generated names and ordering reflect extraction mechanics, not spatial intent.
• Behavioral equivalence still needs the same evaluated-geometry or scalar harness verification used by the hand translations.
• Blender 5 capture items are still a live gap in Geometry Script's generic node builder. The accepted VG Field Value translation creates typed capture items explicitly in script instead of relying on the generated capture_attribute(...) wrapper.

Upstream PR Branch

Branch:

vibegeometry/blender-5-nested-tree-groups

Problem:

• Geometry Script's @tree decorator returns a Python function intended to create a nested node-group node when called inside another @tree.
• Under Blender 5.1, that returned function tries to call geometrynodegroup(...), but no such generated DSL symbol exists.
• Manually calling the generated group(node_tree=...) wrapper returned None in the nested path, so callers could not access group outputs.

Patch:

• In Blender 4/5, create GeometryNodeGroup directly.
• Assign result.node_tree = node_group.
• Wire positional and keyword arguments into enabled group inputs with Geometry Script's existing set_or_create_link(...) helper.
• Return Type(...) wrappers for each enabled group output.

Verification:

• examples/geometry_script/shriinivas_cartesian_helper.py loads external/geometry-script through tools/geometry_script_loader.py.
• VG Cartesian Circle calls vg_cartesian_helper(...) twice inside its own @tree body.
• Generated circle graph contains nested GeometryNodeGroup nodes.
• tools/verify_cartesian_translations.py verifies helper, line, parabola, and circle behavior against the source cartesian.blend groups in Blender 5.1.1.

Fork/PR Todo

• Upstream PR: https://github.com/carson-katri/geometry-script/pull/69
• Keep PR #69 limited to the nested @tree fix. Converter work belongs on vibegeometry/blender-5-nodes-to-script unless it is intentionally prepared as a separate upstream PR.