167 lines
5.9 KiB
Markdown
167 lines
5.9 KiB
Markdown
# Geometry Script Fork Notes
|
|
|
|
VibeGeometry uses a repo-local Geometry Script clone at:
|
|
|
|
```text
|
|
external/geometry-script
|
|
```
|
|
|
|
The clone currently tracks upstream:
|
|
|
|
```text
|
|
https://github.com/carson-katri/geometry-script.git
|
|
```
|
|
|
|
The GameCult fork remote is:
|
|
|
|
```text
|
|
https://github.com/GameCult/geometry-script.git
|
|
```
|
|
|
|
The fork is intentionally kept small. As of 2026-05-04, its live branches are:
|
|
|
|
```text
|
|
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:
|
|
|
|
```powershell
|
|
.\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:
|
|
|
|
```text
|
|
patches/geometry-script/0001-fix-nested-tree-group-references-on-blender-4.patch
|
|
patches/geometry-script/0002-Port-node-tree-conversion-operator.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:
|
|
|
|
```text
|
|
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
|
|
|
|
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:
|
|
|
|
```powershell
|
|
& '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.
|
|
|
|
## Upstream PR Branch
|
|
|
|
Branch:
|
|
|
|
```text
|
|
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.
|