Przejdź do treści
Biblioteka skilli
Projektowanie i UX · Budowanie i kod

geometry-script

/geometry-script

Buduje i edytuje drzewa węzłów Blendera w Pythonie przez dodatek Geometry Script: geometry nodes, shadery, materiały, świat i compositor, także proceduralne generowanie geometrii.

Licencja
GPL-3.0
Ostatnia zmiana repozytorium
13.10.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
1
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 13.10.2026, bez odwołań do wycofanych modeli i API.

Licencja

GPL-3.0, otwarta.

Co robi i kiedy

Buduje i edytuje drzewa węzłów Blendera w Pythonie przez dodatek Geometry Script: geometry nodes, shadery, materiały, świat i compositor, także proceduralne generowanie geometrii.

Oryginalny opis (EN)

Build and edit Blender node trees in Python with the Geometry Script add-on (`from geometry_script import *`, `@tree`; `geometry_script.shader` for `@shader`/`@material`/`@world`; `geometry_script.compositor` for `@compositor`). Use when asked to create, change, debug or inspect a geometry node tree, shader node group, material, world or compositor node group, procedurally generate geometry in Blender, or when a script uses geometry_script — whether through Blender's official MCP server (execute_blender_code) or headless Blender.

Jak działa

  1. The loop
  2. Saving context
  3. Writing trees
  4. Errors and what they mean
  5. Blender 5.x scene snippets
Sekcje z nagłówków SKILL.md, w oryginale · 188 linii, 1 337 słów
Podgląd SKILL.md
---
name: geometry-script
description: Build and edit Blender node trees in Python with the Geometry Script add-on (`from geometry_script import *`, `@tree`; `geometry_script.shader` for `@shader`/`@material`/`@world`; `geometry_script.compositor` for `@compositor`). Use when asked to create, change, debug or inspect a geometry node tree, shader node group, material, world or compositor node group, procedurally generate geometry in Blender, or when a script uses geometry_script — whether through Blender's official MCP server (execute_blender_code) or headless Blender.
---

# Geometry Script

Geometry Script turns a decorated Python function into a Geometry Nodes group.
Every Blender node is a generated, typed function. The add-on checks your
input names, output names, enum values and link types, and its errors say what
to change. **Guess, run and fix from the error.** That is cheaper than reading
up front.

The repo root is two directories above this file. `tools/` and `api/` paths
below are relative to it.

## The loop

1. Write the script to a `.py` file, not an inline string, so later edits are small diffs.
2. Run it and read the short report. Always go through `agent.run`: raw `exec` of
   the same script returns a traceback about 10x longer.
   - **Blender MCP, running Blender:** `execute_blender_code` with
     `from geometry_script import agent; agent.run("/abs/path/script.py", object="Name")`.
     The report comes back as `stdout`.
   - **Blender MCP, no window:** `execute_blender_code_for_cli` with a `blend_file` and
     `from geometry_script import agent; result = agent.run("/abs/path/script.py", object="Name", echo=False)`.
     This tool returns only `result`, not printed output.
   - **No MCP:** `python3 tools/run.py script.py --object Name`
     (add `--blend file.blend` to start from a file).
3. Fix the single error it prints, then run again.
4. Check the result with the report's geometry stats (vertex/face/point/instance
   counts, bounds) and node warnings. Take a viewport screenshot only when what
   it *looks like* matters.

**Live edit:** if the user has the script open in Blender's Text Editor with
Live Edit and the add-on's auto-resolve on, saving the file reruns it. Then
just edit the file and call `agent.status()`, which prints the latest run's report.

`agent.run` prints a few lines and returns them as `{"ok": bool, "report": str}`: each tree built (nodes, inputs, outputs), then the
evaluated geometry and node warnings for every object using those trees.
`object=` attaches the last tree built, or `tree=` if given, to that object,
creating the object if needed. Errors print as `ERROR Type: message` plus the
failing line of your script. Pass `traceback=True` only when that isn't enough.

## Saving context

| Need | Cheap way | Avoid |
|---|---|---|
| Find a node | `python3 tools/describe.py --search "points on faces"` or `agent.search(...)` | grepping `api/nodes.py` (9k+ lines) |
| A node's sockets | `python3 tools/describe.py set_position mesh_to_points` or `agent.describe(...)` | reading the generated function source |
| Shader / compositor nodes | `tools/describe.py --tree shader ...`, `agent.describe(..., tree="compositor")` | grepping `api/shader_nodes.py` / `api/compositor_nodes.py` |
| Check a build | `agent.run(...)` / `tools/run.py` report, or `agent.status()` after a live-edit save | raw `exec` with full tracebacks; screenshots |
| Understand an existing tree | `agent.describe_tree("Name")` (node group, material or world): prints it as Geometry Script calls, without default values | dumping `node_tree.nodes` / links |
| Know the API | this file | the book in `book/` (longer) |
| See the result | report stats first; then MCP `get_screenshot_of_area_as_image(area_ui_type="VIEW_3D", size_limit_in_bytes=200000)` | `get_screenshot_of_window_as_image` (the whole window) |
| A `bpy` (not node) question | MCP `search_api_docs` / `get_python_api_docs` | guessing, or long `dir()` dumps |

Describe only the nodes you're unsure of, and several in one call. Most names
are the node's UI name in snake_case, and the error will tell you if you're wrong.

## Writing trees

```python
from geometry_script import *

@tree("Scatter Cubes")                       # group name; rebuilt in place if it exists
def scatter_cubes(geometry: Geometry, count: int = 4, size: float = 0.3):
    mesh = grid(size_x=4.0, size_y=4.0, vertices_x=count, vertices_y=count).mesh
    points = mesh_to_points(mesh=mesh).points
    cube_mesh = cube(size=(size, size, size)).mesh     # socket tuples -> Combine XYZ
    lifted = set_position(geometry=points, offset=(0.0, 0.0, size * 2)).geometry
    return instance_on_points(points=lifted, instance=cube_mesh).instances
```

- **Inputs:** parameter annotations and defaults become group inputs: `Geometry`, `float`,
  `int`, `bool`, `str`, `Vector`, `Color`, `Rotation`, `Matrix`, `Menu`, `Object`,
  `Material`, `Collection`, `Image`, plus `Field[T]`, `Grid[T]`, `Vector2`. Return one
  value, a tuple, or a dict `{"Output Name": value}` for named outputs.
- **Node functions take keyword arguments only** and return a namedtuple of outputs:
  `mesh_to_points(mesh=m).points`. Enum settings are strings: `mode="FACES"`.
  Type settings (`data_type`, `input_type`) are inferred from what you link, so
  set them only to override.
- **Arithmetic** (`+ - * / % **`, unary `-`) on float, int and vector sockets
  adds Math / Vector Math nodes. Comparisons (`< <= > >= == !=`) add a
  Compare node and give a boolean socket: `z > 0.5`, `index().index % 2 == 0`.
  Combine them with `boolean_math`, not `and`/`or`/`not` or `0 < x < 1`.
  Fields such as `position().position` and `index().index` are plain sockets.
- **Calling a `@tree` function inside another `@tree`** adds a group node. Those
  take positional arguments: `repeat_grid(geometry)`.
- **Builds are all-or-nothing:** if a build raises, the previous tree (and its
  modifier input values) is left untouched. Modifiers keep their input values
  across rebuilds.
- **Names that would shadow Python builtins get a trailing underscore:** `math_`
  (`math(...)` also works, and `math.pi` is still the math module), `id_`,
  `object_`, `string_`.

### Zones

```python
@repeat_zone
def climb(geometry: Geometry, step: float, iteration: int):   # `iteration` is the index
    return set_position(geometry=geometry, offset=(0.0, 0.0, step)).geometry, step * 2.0

@simulation_zone
def fall(geometry: Geometry, delta_time: float):
    return set_position(geometry=geometry, offset=(0.0, 0.0, -1.0)).geometry

@for_each_element(domain="POINT")
def per_point(index: int, radius: float):
    return ForEachResult(main={"scale": radius * 2.0},
                         generated=[{"geometry": uv_sphere(radius=radius).mesh}])

@closure_zone
def scale(x: float, factor: float = 2.0):
    return x * factor

@tree("Zones")
def zones(geometry: Geometry):
    climbed = climb(geometry, 1.0, iterations=4).geometry
    out = per_point(mesh_to_points(mesh=climbed).points, radius=0.25)
    value = scale.evaluate(scale(), 1.0, 3.0)
    return {"Geometry": fall(out.generated.geometry), "Value": value}
```

### Shaders, materials, worlds and the compositor

Each tree type has its own module of node functions; names like `normal`, `mix`
or `object_info` mean different nodes in each. A node used in the wrong tree
raises an error naming the module it belongs to.

```python
from geometry_script import *            # geometry nodes, @tree / @geometry
from geometry_script import shader as sh # @sh.shader, @sh.material, @sh.world
from geometry_script import compositor as comp

@sh.shader("Stripes")                    # shader node group: works like @tree
def stripes(color: Color = (0.9, 0.3, 0.1, 1.0), scale: float = 6.0):
    wave = sh.wave_texture(scale=scale)
    return sh.mix(data_type="RGBA", factor=wave.factor, a=color, b=(0, 0, 0, 1)).result

@sh.material("Striped")                  # no parameters; return the surface shader,
def striped():                           # or {"surface": ..., "displacement": ...}
    return sh.principled_bsdf(base_color=stripes(scale=10.0)).bsdf

@sh.world("Studio", scene=True)          # scene=True makes it the scene's world
def studio():
    return sh.background(color=(0.05, 0.06, 0.08, 1.0)).background

@comp.compositor("Glow", scene=True)     # scene=True makes it the scene's compositor
def glow(strength: float = 0.3):
    image = comp.render_layers().image
    blurred = comp.blur(image=image, size=(20, 20)).image
    return comp.mix(data_type="RGBA", blend_type="SCREEN", factor=strength, a=image, b=blurred).result

@tree("Striped Cube")                    # calling a @material returns the Material
def striped_cube():
    return set_material(geometry=cube().mesh, material=striped()).geometry
```

`@repeat_zone` and `@closure_zone` also work in shader trees. `agent.run` reports
shader groups, materials and worlds, but `object=` only attaches geometry trees.

### Item nodes

Capture Attribute, Index/Menu Switch, Bundles and Format String take their
items as keyword arguments, `items=[...]` or `items={...}`, and expose them by
name: `capture_attribute(geometry=g, height=position().position).height`.

## Errors and what they mean

| Error | Fix |
|---|---|
| `unexpected keyword argument 'offest'. Did you mean 'offset'?` | Rename it. |
| `...Outputs has no output 'geometry'; available: ['points']` | Use a listed name. |
| `has no 'vector' output with its current settings {'operation': 'DOT_PRODUCT'}; available: ['value']` | That mode outputs something else; use a listed output or change the setting. |
| `Cannot set ...mode to 'VERTEX'. Expected one of [...]. Did you mean 'VERTICES'?` | Use a listed value. |
| `has no 'x' input with its current settings {...}` | That input only exists in another mode or type. |
| `Invalid links ... cannot take ... Set the node's type, one of: ...` | Wrong socket type, or set `data_type=`/`input_type=`. |
| `takes 0 positional arguments` | Node functions are keyword-only. |
| `NameError: name 'foo' is not defined` | Wrong node name: run `tools/describe.py --search foo`. |

Watch out: Blender silently converts some types (float → vector, bool → float),
so a link of the wrong kind can still build. Check the result stats.

## Blender 5.x scene snippets

- Attach by hand: `mod = obj.modifiers.new("GS", "NODES"); mod.node_group = bpy.data.node_groups["Name"]`
  (`agent.run(..., object=...)` does this for you).
- Modifier input values: `getattr(mod.properties.inputs, socket.identifier).value = 5.0`,
  where `socket = mod.node_group.interface.items_tree["Height"]`. The old
  `mod["Socket_1"]` form no longer works in Blender 5.

Wersje

W bazie nie ma innych skilli o nazwie geometry-script.

Migawka bazy z 13.11.2026 · wersja paczki 6328ba0e0d04 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100blender-syntax-nodes
    Buduje drzewa węzłów Blendera przez Python: Geometry Nodes, Shader Nodes i Compositor, z interfejsem NodeTreeInterface w wersji 4.0+.
  • 100nodebpy
    Buduje, edytuje i weryfikuje drzewa węzłów Blendera jako kod Pythona przez bibliotekę nodebpy, w tym Geometry Nodes i materiały.
  • 100nodebpy
    Buduje, edytuje i weryfikuje drzewa węzłów Blendera (Geometry Nodes, materiały, kompozytor) jako kod Pythona w bibliotece nodebpy, w tym to_python i klasy grup węzłów.
  • 90procedural-blender-nodes
    Buduje i debuguje proceduralne systemy węzłów w Blenderze z Pythona: generatory Geometry Nodes, materiały i animacje.
  • 100blender-geometry-nodes
    Prowadzi proceduralne modelowanie w Geometry Nodes Blendera: systemy rozpraszania, drzewa węzłów, projektowanie parametryczne i instancje.
  • 100blender-impl-nodes
    Buduje w Blenderze przez Python węzły Geometry i Shader Nodes: parametryczne modele i generowane materiały dla AEC.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.