diff --git a/docs/research/procedural-doctrine.md b/docs/research/procedural-doctrine.md index 2c36e04..68b43e7 100644 --- a/docs/research/procedural-doctrine.md +++ b/docs/research/procedural-doctrine.md @@ -21,6 +21,48 @@ to recover wiring, defaults, socket order, and hidden graph structure. Do not copy their naming, ordering, or mechanical transcript shape into accepted Geometry Script. A useful draft can still be ugly enough to need supervision. +## Python Is The Authoring Layer + +Do not treat Geometry Script as the whole toolchain. It is the graph-emission +surface: the part that turns intent into inspectable Geometry Nodes groups. +Python is where intent can be structured before it becomes nodes. + +Reach for ordinary Python when the design has repetition, tables, named parts, +variants, cleanup rules, validation, generated docs, render orchestration, or +scene setup. The goal is not to hide geometry in imperative mesh code. The goal +is to use Python to organize the graph authoring problem so the emitted node +groups stay legible. + +Useful split: + +```text +Python data/functions -> Geometry Script node groups -> bpy scene orchestration -> Blender evaluation/render +``` + +Example: a seven-segment display is clearer as a Python table of named bar +placements feeding repeated `vg_create_segment(...)` calls than as hand-copied +node sprawl. + +```python +SEGMENT_PLACEMENTS = [ + ("top", True, (0.0, "vertical_segment_size")), + ("middle", True, (0.0, 0.0)), + ("bottom", True, (0.0, "negative_vertical_segment_size")), +] + +for name, x_major, offset_terms in SEGMENT_PLACEMENTS: + # In accepted scripts, expand symbolic terms into Geometry Script values + # before calling the node group. + segment = vg_create_segment(x_major=x_major, offset=offset_vector) +``` + +Metaphor in use: Python is the drafting table. Geometry Script is the machine +shop. `bpy` is the crane, paint booth, camera rig, and inspection station. Do +not ask the machine shop to be the whole factory. + +Verification cue: if Python generates graph structure, verify the emitted node +groups and evaluated behavior, not the Python loop by itself. + ## Start With A Pipeline Reach for this when the form feels like it has stages: a seed shape, a sampling diff --git a/notes/fresh-workspace-handoff.md b/notes/fresh-workspace-handoff.md index 0c27549..606d5a7 100644 --- a/notes/fresh-workspace-handoff.md +++ b/notes/fresh-workspace-handoff.md @@ -50,6 +50,11 @@ explain when a tool becomes salient for a visual form, the mental move that turns the form into graph structure, a small code sketch, and the verification cue. +Current authoring prior: use the full Python stack. Python structures intent, +tables, loops, variants, cleanup, validation, docs, and scene/render +orchestration; Geometry Script emits inspectable Geometry Nodes groups; `bpy` +handles Blender scene machinery and evaluated evidence. + The repo-local Geometry Script clone has a Blender 5.1 patch for nested `@tree` group reuse plus a ported `nodes_to_script` converter. See `docs/research/geometry-script-fork-notes.md`. @@ -72,6 +77,8 @@ wrapper around the full `Field Value` group rather than an independent helper. - Target Blender 5.0+ unless the task says otherwise. - Geometry nodes are the primary procedural geometry surface. +- Python is the authoring/orchestration layer, not a fallback after Geometry + Script runs out of rope. - Python constructs and orchestrates graphs; it should not bury the design in opaque imperative mesh generation. - Visual target evidence must remain attached to scene briefs and render diff --git a/state/evidence.jsonl b/state/evidence.jsonl index 2036785..1167fae 100644 --- a/state/evidence.jsonl +++ b/state/evidence.jsonl @@ -21,3 +21,4 @@ {"ts": "2026-05-04T13:51:58+00:00", "type": "documentation", "status": "accepted", "note": "Audited procedural doctrine snippets against the verified Geometry Script translations and removed conceptual shorthand. Doctrine snippets should use the same explicit Geometry Script node-call style as the scripts that passed Blender verification, with excerpts clearly behaving as excerpts rather than pseudocode."} {"ts": "2026-05-04T14:10:09+00:00", "type": "tooling", "status": "accepted", "note": "Ported upstream Geometry Script nodes_to_script prototype onto GameCult fork branch vibegeometry/blender-5-nodes-to-script. Added callable convert_node_tree(tree), UI operator registration, patch persistence, and a Blender smoke harness. In Blender 5.1.1 the converter emits compiling draft scripts for Create Decimal, Digit At, Next Digit, Seven Segments, Delete Segments, and the 176-node Field Value group; generated output is a bootstrap draft requiring cleanup and behavioral verification."} {"ts": "2026-05-04T14:32:43+00:00", "type": "doctrine", "status": "accepted", "note": "nodes_to_script output is evidence and scaffolding, not style guidance. Use it to recover wiring/defaults/socket order and hidden graph structure, then rewrite into doctrine-quality Geometry Script with spatial names, intentional decomposition, and behavioral verification."} +{"ts": "2026-05-04T14:35:46+00:00", "type": "doctrine", "status": "accepted", "note": "Updated VibeGeometry priors: Python is the authoring and orchestration layer, Geometry Script is the inspectable node-graph emission surface, bpy handles Blender scene/render/evaluation machinery, and external Python tools handle inspection, converter drafts, verification, docs, and corpus evidence. Do not reason as if the Geometry Script DSL is the whole toolchain."} diff --git a/state/map.yaml b/state/map.yaml index 1edf11a..c757038 100644 --- a/state/map.yaml +++ b/state/map.yaml @@ -20,6 +20,7 @@ hard_boundaries: - Blender 5.0+ is the target runtime unless a task explicitly chooses another version. - Geometry nodes are the primary procedural modeling surface. - Python scripts should construct and orchestrate node graphs, not hide the design in uninspectable imperative mesh code. + - Python is the authoring and orchestration layer; Geometry Script is the inspectable node-graph emission surface, not the whole toolchain. - Visual targets must preserve reference-image evidence and explicit instructions. - A graph that runs is not accepted until rendered output is inspected against the target. - Node groups must be named, parameterized, and legible enough for future agents to modify. @@ -37,6 +38,11 @@ live_architecture: - Generate Blender Python that builds the scene and node graphs from the manifest. - Run Blender headlessly or interactively to produce `.blend` files and render evidence. - Review renders against the visual target and record accepted, rejected, or revised hypotheses. + authoring_stack: + - Python structures intent, repetition, data tables, variants, cleanup, validation, documentation, and scene/render orchestration. + - Geometry Script emits inspectable reusable Geometry Nodes groups. + - bpy handles Blender objects, modifiers, materials, cameras, lights, files, renders, and evaluated-geometry checks. + - External Python tools inspect source blends, generate converter drafts, compare outputs, and maintain corpus evidence. persistence: - `state/map.yaml` stores canonical mission, boundaries, architecture, artifacts, and next action. - `state/scratch.md` stores one bounded active thought surface.