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

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 patch branch, and applies the patch stored in:

patches/geometry-script/0001-fix-nested-tree-group-references-on-blender-4.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.

Active Patch 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 external/geometry-script on vibegeometry/blender-5-nested-tree-groups until that PR is merged or a better maintained fork replaces it.