diff --git a/docs/README.skills.md b/docs/README.skills.md index 69e0c027..2ac60176 100644 --- a/docs/README.skills.md +++ b/docs/README.skills.md @@ -312,6 +312,7 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-skills) for guidelines on how to | [resemble-detect](../skills/resemble-detect/SKILL.md)
`gh skills install github/awesome-copilot resemble-detect` | Deepfake detection and media safety — detect AI-generated audio, images, video, and text, trace synthesis sources, apply watermarks, verify speaker identity, and analyze media intelligence using Resemble AI | `LICENSE`
`references/api-reference.md` | | [review-and-refactor](../skills/review-and-refactor/SKILL.md)
`gh skills install github/awesome-copilot review-and-refactor` | Review and refactor code in your project according to defined instructions | None | | [reviewing-oracle-to-postgres-migration](../skills/reviewing-oracle-to-postgres-migration/SKILL.md)
`gh skills install github/awesome-copilot reviewing-oracle-to-postgres-migration` | Identifies Oracle-to-PostgreSQL migration risks by cross-referencing code against known behavioral differences (empty strings, refcursors, type coercion, sorting, timestamps, concurrent transactions, etc.). Use when planning a database migration, reviewing migration artifacts, or validating that integration tests cover Oracle/PostgreSQL differences. | `references/REFERENCE.md`
`references/empty-strings-handling.md`
`references/no-data-found-exceptions.md`
`references/oracle-parentheses-from-clause.md`
`references/oracle-to-postgres-sorting.md`
`references/oracle-to-postgres-timestamp-timezone.md`
`references/oracle-to-postgres-to-char-numeric.md`
`references/oracle-to-postgres-type-coercion.md`
`references/postgres-concurrent-transactions.md`
`references/postgres-refcursor-handling.md` | +| [rhino3d-scripts](../skills/rhino3d-scripts/SKILL.md)
`gh skills install github/awesome-copilot rhino3d-scripts` | Authoring and debugging scripts for Rhinoceros 3D (Rhino 8 and later). Use when asked to write RhinoScript (VBScript / .rvb / .vbs), RhinoPython, or RhinoCommon-based scripts; automate Rhino modeling tasks; build command macros; manipulate Rhino geometry, layers, blocks, or document objects; pick objects from the viewport; control redraw and undo; or load and run scripts from the Rhino Script Editor. Covers `rhinoscriptsyntax`, `scriptcontext`, the `Rhino.*` RhinoCommon namespaces (`Rhino.Geometry`, `Rhino.DocObjects`, `Rhino.Input`, `Rhino.UI`, `Rhino.Display`, `Rhino.FileIO`), and the Rhino 8 unified Script Editor. | `references/macros-and-loading.md`
`references/rhinocommon-map.md`
`references/rhinoscriptsyntax-cheatsheet.md`
`references/vbscript-quirks.md` | | [roundup](../skills/roundup/SKILL.md)
`gh skills install github/awesome-copilot roundup` | Generate personalized status briefings on demand. Pulls from your configured data sources (GitHub, email, Teams, Slack, and more), synthesizes across them, and drafts updates in your own communication style for any audience you define. | None | | [roundup-setup](../skills/roundup-setup/SKILL.md)
`gh skills install github/awesome-copilot roundup-setup` | Interactive onboarding that learns your communication style, audiences, and data sources to configure personalized status briefings. Paste in examples of updates you already write, answer a few questions, and roundup calibrates itself to your workflow. | `references/config-template.md` | | [ruby-mcp-server-generator](../skills/ruby-mcp-server-generator/SKILL.md)
`gh skills install github/awesome-copilot ruby-mcp-server-generator` | Generate a complete Model Context Protocol server project in Ruby using the official MCP Ruby SDK gem. | None | diff --git a/skills/rhino3d-scripts/SKILL.md b/skills/rhino3d-scripts/SKILL.md new file mode 100644 index 00000000..d7b467b0 --- /dev/null +++ b/skills/rhino3d-scripts/SKILL.md @@ -0,0 +1,166 @@ +--- +name: rhino3d-scripts +description: 'Authoring and debugging scripts for Rhinoceros 3D (Rhino 8 and later). Use when asked to write RhinoScript (VBScript / .rvb / .vbs), RhinoPython, or RhinoCommon-based scripts; automate Rhino modeling tasks; build command macros; manipulate Rhino geometry, layers, blocks, or document objects; pick objects from the viewport; control redraw and undo; or load and run scripts from the Rhino Script Editor. Covers `rhinoscriptsyntax`, `scriptcontext`, the `Rhino.*` RhinoCommon namespaces (`Rhino.Geometry`, `Rhino.DocObjects`, `Rhino.Input`, `Rhino.UI`, `Rhino.Display`, `Rhino.FileIO`), and the Rhino 8 unified Script Editor.' +--- + +# Rhino 3D Scripting Skill + +Write production-quality scripts for Rhinoceros 3D. Covers the three scripting surfaces (RhinoScript/VBScript, RhinoPython, direct RhinoCommon .NET) and the Rhino 8+ Script Editor. + +## When to Use This Skill + +- User asks to write, edit, or debug a `.rvb`, `.vbs`, or `.py` Rhino script +- User wants a Rhino **command macro** or wants to automate a sequence of Rhino commands +- User wants to manipulate geometry, layers, blocks, materials, viewports, or annotations from code +- User mentions `rhinoscriptsyntax`, `scriptcontext`, `RhinoCommon`, `Rhino.Geometry`, `RhinoDoc`, or the Script Editor +- User wants to pick objects, prompt for input, or build a small UI inside Rhino +- User asks how to load, run, or distribute a script (startup scripts, aliases, toolbar buttons) + +## Choosing a Scripting Surface + +Pick the surface based on the task, not preference. Recommend Python by default for new work. + +| Surface | When to choose | File ext | +|---|---|---| +| **RhinoPython** (`rhinoscriptsyntax` + RhinoCommon) | Default for new scripts. Best ecosystem, readable, full RhinoCommon access. | `.py` | +| **RhinoScript** (VBScript) | Maintaining legacy `.rvb`/`.vbs` files; integrating with VBA/COM. | `.rvb`, `.vbs` | +| **RhinoCommon (C#/.NET) via Script Editor** | Performance-critical loops, complex geometry, leveraging .NET libraries. | `.cs` | +| **Command macro** | Pure sequence of existing Rhino commands; no logic. | toolbar/alias | + +A macro is **not** a script — it is a string of command-line input (e.g. `! _-Line 0,0,0 10,0,0 _Enter`). Use a script the moment you need a variable, loop, or conditional. + +## Prerequisites + +- Rhino 7 or later (Rhino 8 strongly recommended — unified Script Editor supports Python 3, VB, and C# in one window). +- Script Editor: type `_ScriptEditor` (Rhino 8) or `_EditPythonScript` / `_EditScript` (older). +- Run a saved file from the command line with `_-RunPythonScript` or `_LoadScript` + `_RunScript`. + +## Core Patterns + +### Python: minimal scaffold + +```python +import rhinoscriptsyntax as rs +import scriptcontext as sc +import Rhino + +def main(): + obj_id = rs.GetObject("Select a curve", filter=rs.filter.curve, preselect=True) + if not obj_id: + return + length = rs.CurveLength(obj_id) + print("Length: {0:.4f}".format(length)) + +if __name__ == "__main__": + main() +``` + +### Python: working with RhinoCommon directly + +```python +import Rhino +import scriptcontext as sc + +doc = sc.doc # Rhino.RhinoDoc.ActiveDoc +tol = doc.ModelAbsoluteTolerance + +circle = Rhino.Geometry.Circle(Rhino.Geometry.Point3d(0, 0, 0), 5.0) +curve_id = doc.Objects.AddCircle(circle) +doc.Views.Redraw() +``` + +### VBScript: minimal scaffold + +```vbscript +Option Explicit + +Call Main() + +Sub Main() + Dim strObject + strObject = Rhino.GetObject("Select a curve", 4) ' 4 = curve filter + If IsNull(strObject) Then Exit Sub + Rhino.Print "Length: " & Rhino.CurveLength(strObject) +End Sub +``` + +### Picking objects with a custom filter (Python, RhinoCommon) + +```python +import Rhino +import scriptcontext as sc + +go = Rhino.Input.Custom.GetObject() +go.SetCommandPrompt("Select breps") +go.GeometryFilter = Rhino.DocObjects.ObjectType.Brep +go.SubObjectSelect = False +go.GetMultiple(1, 0) +if go.CommandResult() != Rhino.Commands.Result.Success: + pass +else: + ids = [go.Object(i).ObjectId for i in range(go.ObjectCount)] +``` + +## Step-by-Step Workflows + +### Bulk-modify many objects fast + +1. Disable redraw: `rs.EnableRedraw(False)`. +2. Wrap mutations in a single undo record: `undo = doc.BeginUndoRecord("My Op")` … `doc.EndUndoRecord(undo)`. +3. Use RhinoCommon directly inside the loop (skip `rhinoscriptsyntax` overhead). +4. Re-enable redraw and call `doc.Views.Redraw()` in a `try`/`finally` so a crash never leaves the viewport frozen. + +### Distribute a script to a teammate + +1. Save the `.py` / `.rvb` somewhere on disk. +2. Add the folder to `Options → Files → Search paths` so Rhino can find it by name. +3. Create a toolbar button or alias whose macro is: + - Python: `! _-RunPythonScript "MyScript.py"` + - RhinoScript: `! _-LoadScript "MyScript.rvb" _-RunScript MySubName` +4. The leading `!` cancels any running command; `-` runs the command in script (no-dialog) mode. + +### Run code at Rhino startup + +1. Place a `.rvb`/`.py` in a search path. +2. `Tools → Options → RhinoScript` (or `Python`) → add to **Startup** list. The file executes once per session. + +## Gotchas + +- **`rhinoscriptsyntax` returns GUIDs, RhinoCommon returns objects.** Mixing them is fine, but `doc.Objects.Find(guid)` is the bridge from a `rs.*` id to a `RhinoObject`. +- **Coordinates differ by surface.** Python uses `(x, y, z)` tuples *or* `Rhino.Geometry.Point3d`; VBScript uses 3-element `Array(x, y, z)`. Never pass a Python list to a VBScript helper through COM. +- **`Option Explicit` is off by default in VBScript.** Typos silently create new variables. Always add `Option Explicit` at the top of `.rvb` files. +- **VBScript has no block scope.** All `Dim`s inside a `Sub` are hoisted to the top of the procedure. Loop counters leak. +- **`Nothing`, `Empty`, and `Null` are different** in VBScript. Use `IsNull` for `Rhino.GetObject` failure, `IsEmpty` for uninitialized `Variant`, `Is Nothing` for object refs. +- **Parentheses change calling semantics in VBScript.** `Call Foo(a, b)` and `Foo a, b` are valid; `Foo(a, b)` (no `Call`, with parens) is **not** a call to a Sub — it’s a syntax error for multi-arg subs and a forced `ByVal` for single-arg. +- **Tolerance is per-document.** Always read `doc.ModelAbsoluteTolerance` rather than hardcoding `0.001`; users work in mm, m, inches, etc. +- **Long loops should poll `Rhino.RhinoApp.EscapeKeyPressed`** so the user can cancel. Otherwise Rhino appears frozen. +- **GUID strings vs `System.Guid`.** `rhinoscriptsyntax` accepts either; RhinoCommon wants `System.Guid`. Convert with `System.Guid(str_id)` if needed. +- **Don’t call `doc.Views.Redraw()` inside a tight loop.** Toggle redraw once outside the loop. +- **`.rvb` is just `.vbs` renamed** with a Rhino-specific extension so Rhino’s `LoadScript` recognizes it. Same VBScript engine. + +## Troubleshooting + +| Symptom | Fix | +|---|---| +| `rs.GetObject` returns `None` immediately | The user pressed Escape, or your `filter` excludes everything. Re-check `rs.filter.*` flags. | +| “Unable to find script” when running by name | The folder isn’t in `Options → Files → Search paths`. | +| VBScript `Type mismatch` on coordinates | You passed a 2-element array. Rhino requires 3-element `Array(x, y, z)`. | +| Python `ImportError: No module named Rhino` | You’re running CPython outside Rhino. RhinoCommon is only available in Rhino’s embedded Python (or via `rhino3dm` for read-only file work). | +| Created geometry doesn’t appear | You forgot `doc.Views.Redraw()`, or `rs.EnableRedraw(False)` was never re-enabled. | +| Undo undoes only the last object of a batch | Wrap the batch in `BeginUndoRecord` / `EndUndoRecord`. | +| Script works alone but fails as a startup script | Startup runs before any document is open — return early or skip document-dependent work when `sc.doc is None`. | +| `rs.Command("...")` returns `False` | The macro string is malformed. Prefix with `!` and `-`, end every prompt with `_Enter` or a value. | + +## References + +- [references/rhinoscriptsyntax-cheatsheet.md](references/rhinoscriptsyntax-cheatsheet.md) — most-used `rs.*` functions by category. +- [references/rhinocommon-map.md](references/rhinocommon-map.md) — which namespace to import for which task. +- [references/macros-and-loading.md](references/macros-and-loading.md) — command-line macro syntax, `LoadScript` / `RunScript`, search paths. +- [references/vbscript-quirks.md](references/vbscript-quirks.md) — VBScript-only traps relevant to RhinoScript. + +### Upstream docs + +- RhinoScript landing: +- Developer hub: +- RhinoCommon API index: +- Example scripts repo: diff --git a/skills/rhino3d-scripts/references/macros-and-loading.md b/skills/rhino3d-scripts/references/macros-and-loading.md new file mode 100644 index 00000000..df524781 --- /dev/null +++ b/skills/rhino3d-scripts/references/macros-and-loading.md @@ -0,0 +1,95 @@ +# Macros, Loading, and Running Scripts + +## Command Macros (no script needed) + +A macro is a string of command-line input. Anywhere Rhino accepts a command (alias, toolbar button, `_ReadCommandFile`), you can place a macro. + +### Syntax rules + +| Token | Meaning | +|---|---| +| `!` | **Cancel** any currently running command before this one starts. Always start macros with `!`. | +| `_` | Use the **English** (invariant) command name, so the macro works in any locale. | +| `-` | Run the command in **script mode** — suppress dialogs, accept input from the macro string. | +| `_Enter` | Press Enter at the current prompt. | +| `Pause` | Stop and wait for the user to supply this input interactively. | +| `;` | Comment to end of line. | +| Newline | Same as a space — a separator between tokens, not a command terminator. | + +### Example macros + +```text +! _-Line 0,0,0 10,0,0 +! _-Circle 0,0,0 5 _Enter +! _SelAll _Delete +! _-Properties _Object _Name "MyObject" _EnterEnd _Enter +! _-RunPythonScript "MyScript.py" +``` + +## Running Saved Scripts + +### Python (`.py`) + +```text +_-RunPythonScript "C:\Users\example\Scripts\MyScript.py" +``` + +Or, with the script folder on the search path: + +```text +_-RunPythonScript "MyScript.py" +``` + +`_EditPythonScript` opens the legacy editor; `_ScriptEditor` (Rhino 8) opens the unified editor with Python 3, VB, and C#. + +### RhinoScript (`.rvb`, `.vbs`) + +Two steps: **load** the file (registers its subs/functions), then **run** a named sub. + +```text +_-LoadScript "MyScript.rvb" +_-RunScript MyMainSub +``` + +A single `.rvb` can hold many subs; `_RunScript` chooses which to invoke. + +### Search Paths + +`Options → Files → Search paths` — folders listed here are scanned when you reference a script by bare filename. Without this, you must give a full path. + +### Startup Scripts + +`Options → RhinoScript → Startup` (and `Options → Python → Startup`) — files in these lists run once when Rhino opens. Useful for registering custom commands or aliases. + +**Guard against missing document** in startup code: + +```python +import scriptcontext as sc + +def startup(): + if sc.doc is None: + return + +startup() +``` + +## Toolbar Buttons & Aliases + +A toolbar button’s **Command** field is just a macro. To make a button that runs your script: + +```text +! _-RunPythonScript "MyScript.py" +``` + +Set the **Tooltip** to a short description; set the icon via the button editor. + +To create an alias: `Options → Aliases → New`. The alias name becomes a typed command; its value is the macro. + +## Invoking Macros From a Script + +```python +import rhinoscriptsyntax as rs +rs.Command("! _-Line 0,0,0 10,0,0", echo=False) +``` + +`echo=False` suppresses command-history output but does **not** suppress prompts — always use `-` and complete every prompt within the macro string. diff --git a/skills/rhino3d-scripts/references/rhinocommon-map.md b/skills/rhino3d-scripts/references/rhinocommon-map.md new file mode 100644 index 00000000..b1bdad22 --- /dev/null +++ b/skills/rhino3d-scripts/references/rhinocommon-map.md @@ -0,0 +1,90 @@ +# RhinoCommon Namespace Map + +Use this to decide which `Rhino.*` namespace to import for a task. All of these are accessible from Python with `import Rhino`. + +## Document & Object Model + +| Need | Namespace | Key types | +|---|---|---| +| The active document, units, tolerances, undo | `Rhino` | `RhinoDoc`, `RhinoApp` | +| Reading/writing objects in the doc | `Rhino.DocObjects` | `RhinoObject`, `ObjectAttributes`, `Layer`, `ObjectType` | +| Tables (layers, materials, blocks, dim styles) | `Rhino.DocObjects.Tables` | `LayerTable`, `InstanceDefinitionTable`, `MaterialTable` | +| Custom per-object user data | `Rhino.DocObjects.Custom` | `UserData` | +| File I/O (.3dm, import/export) | `Rhino.FileIO` | `File3dm`, `File3dmObject` | + +## Geometry + +| Need | Namespace | Key types | +|---|---|---| +| Points, vectors, transforms | `Rhino.Geometry` | `Point3d`, `Vector3d`, `Transform`, `Plane`, `BoundingBox` | +| Curves | `Rhino.Geometry` | `Curve`, `NurbsCurve`, `PolylineCurve`, `LineCurve`, `ArcCurve` | +| Surfaces & breps | `Rhino.Geometry` | `Surface`, `NurbsSurface`, `Brep`, `BrepFace`, `Extrusion` | +| Meshes | `Rhino.Geometry` | `Mesh`, `MeshFace`, `MeshNgon` | +| SubD | `Rhino.Geometry` | `SubD`, `SubDFace`, `SubDEdge` | +| Geometry collections (vertices, edges, faces lists) | `Rhino.Geometry.Collections` | `MeshVertexList`, `BrepEdgeList` | +| Intersections | `Rhino.Geometry.Intersect` | `Intersection`, `CurveIntersections` | +| Mesh refinement | `Rhino.Geometry.MeshRefinements` | | +| Space morphs (bend, twist, etc.) | `Rhino.Geometry.Morphs` | `BendSpaceMorph`, `TwistSpaceMorph` | + +## User Interaction + +| Need | Namespace | Key types | +|---|---|---| +| Prompts, getters, command results | `Rhino.Input` / `Rhino.Input.Custom` | `RhinoGet`, `GetObject`, `GetPoint`, `GetOption` | +| Commands (when building a plugin) | `Rhino.Commands` | `Command`, `Result` | +| Forms, dialogs, panels | `Rhino.UI` | `Dialog`, `Panels`, `RhinoEtoExtensions` | +| UI controls / data sources | `Rhino.UI.Controls` | | +| Gumball | `Rhino.UI.Gumball` | | + +## Display & Rendering + +| Need | Namespace | Key types | +|---|---|---| +| Viewports, display conduits, draw overlays | `Rhino.Display` | `DisplayPipeline`, `DisplayConduit`, `RhinoViewport` | +| Render content (materials, environments) | `Rhino.Render` | `RenderContent`, `RenderMaterial`, `RenderTexture` | +| Render mesh customization | `Rhino.Render.CustomRenderMeshes` | | +| Post effects | `Rhino.Render.PostEffects` | | + +## Runtime & Plugins + +| Need | Namespace | Key types | +|---|---|---| +| Plugin lifecycle, settings | `Rhino.PlugIns` | `PlugIn`, `FileImportPlugIn`, `FileExportPlugIn` | +| In-process Rhino (run Rhino from external .NET) | `Rhino.Runtime.InProcess` | `RhinoCore` | +| Native interop (pointers, marshalling) | `Rhino.Runtime.InteropWrappers` | | +| User notifications (toasts) | `Rhino.Runtime.Notifications` | | + +## Common Patterns + +```python +import Rhino +import scriptcontext as sc +import System.Drawing + +doc = sc.doc # Rhino.RhinoDoc +tol = doc.ModelAbsoluteTolerance # float +view = doc.Views.ActiveView # Rhino.Display.RhinoView +layer_index = doc.Layers.Add("MyLayer", System.Drawing.Color.Red) + +# Find a Rhino object from a rhinoscriptsyntax GUID +rhobj = doc.Objects.Find(guid) # Rhino.DocObjects.RhinoObject +geom = rhobj.Geometry # Rhino.Geometry.GeometryBase + +# Add geometry with attributes +attrs = Rhino.DocObjects.ObjectAttributes() +attrs.LayerIndex = layer_index +attrs.Name = "example" +new_id = doc.Objects.AddCurve(curve, attrs) +``` + +## Undo + +```python +undo_serial = doc.BeginUndoRecord("Batch Op") +try: + # ... many doc.Objects.* calls ... + pass +finally: + doc.EndUndoRecord(undo_serial) + doc.Views.Redraw() +``` diff --git a/skills/rhino3d-scripts/references/rhinoscriptsyntax-cheatsheet.md b/skills/rhino3d-scripts/references/rhinoscriptsyntax-cheatsheet.md new file mode 100644 index 00000000..87a0a67a --- /dev/null +++ b/skills/rhino3d-scripts/references/rhinoscriptsyntax-cheatsheet.md @@ -0,0 +1,108 @@ +# `rhinoscriptsyntax` Cheatsheet + +```python +import rhinoscriptsyntax as rs +``` + +## User Input + +| Function | Returns | +|---|---| +| `rs.GetObject(message, filter, preselect, select)` | GUID or `None` | +| `rs.GetObjects(message, filter)` | list of GUIDs | +| `rs.GetPoint(message, base_point)` | `Point3d` or `None` | +| `rs.GetString(message, default, strings)` | str | +| `rs.GetInteger`, `rs.GetReal` | int / float | +| `rs.GetBoolean(message, items, defaults)` | list of bools | + +Common `rs.filter.*` flags (OR them together): + +``` +point=1, point_cloud=2, curve=4, surface=8, polysurface=16, +mesh=32, light=256, annotation=512, instance_reference=4096, +text_dot=8192, grip=16384, detail=32768, hatch=65536, +morph_control=131072, sub_d=262144 +``` + +## Creating Geometry + +| Function | Notes | +|---|---| +| `rs.AddPoint(point)` | | +| `rs.AddLine(start, end)` | | +| `rs.AddPolyline(points)` | `points` is a list of 3-tuples | +| `rs.AddCircle(plane_or_center, radius)` | | +| `rs.AddArc(plane, radius, angle_deg)` | angle in **degrees** | +| `rs.AddCurve(points, degree=3)` | NURBS through control points | +| `rs.AddInterpCurve(points, degree=3)` | NURBS through points | +| `rs.AddSphere(center, radius)` | | +| `rs.AddBox(corners)` | `corners` = 8 points | +| `rs.AddPlanarSrf(curves)` | returns list | +| `rs.AddLoftSrf(curves, ...)` | returns list of GUIDs | +| `rs.AddExtrusion(profile, path)` / `rs.ExtrudeCurveStraight` | | + +## Object Properties + +| Function | Purpose | +|---|---| +| `rs.ObjectLayer(id [, layer])` | get/set | +| `rs.ObjectColor(id [, color])` | RGB tuple | +| `rs.ObjectName(id [, name])` | | +| `rs.ObjectType(id)` | int matching `rs.filter.*` | +| `rs.IsCurve / IsSurface / IsBrep / IsMesh / IsPoint(id)` | | +| `rs.DeleteObject(id)` / `rs.DeleteObjects(ids)` | | +| `rs.CopyObject(id, translation)` | | +| `rs.MoveObject(id, translation)` | | +| `rs.RotateObject(id, center, angle, axis=None, copy=False)` | angle in degrees | +| `rs.ScaleObject(id, origin, scale)` | scale is a 3-tuple | + +## Curves + +| Function | | +|---|---| +| `rs.CurveLength(id)` | | +| `rs.CurveDomain(id)` | `(t0, t1)` | +| `rs.EvaluateCurve(id, t)` | `Point3d` | +| `rs.CurveStartPoint / CurveEndPoint(id)` | | +| `rs.CurveClosestPoint(id, point)` | parameter `t` | +| `rs.DivideCurve(id, segments, create_points=False, return_points=True)` | | +| `rs.IsCurveClosed / IsCurvePlanar(id)` | | + +## Layers + +| Function | | +|---|---| +| `rs.AddLayer(name, color=None, visible=True, locked=False, parent=None)` | | +| `rs.CurrentLayer([layer])` | | +| `rs.LayerNames()` | list | +| `rs.LayerVisible(name [, visible])` | | +| `rs.DeleteLayer(name)` | | +| `rs.ObjectsByLayer(name)` | list of GUIDs | + +## Document & View + +| Function | | +|---|---| +| `rs.UnitAbsoluteTolerance()` | | +| `rs.UnitSystem()` | int (`rs.unit_system_*`) | +| `rs.EnableRedraw(enable)` | **toggle this around bulk ops** | +| `rs.Redraw()` | force one redraw | +| `rs.ViewNames()` / `rs.CurrentView([name])` | | +| `rs.ZoomExtents(view=None, all=False)` | | + +## Selection + +| Function | | +|---|---| +| `rs.SelectedObjects()` | list | +| `rs.SelectObject(id)` / `rs.SelectObjects(ids)` | | +| `rs.UnselectAllObjects()` | | +| `rs.InvertSelectedObjects()` | | + +## Macros from Script + +`rs.Command(command_string, echo=True)` runs a macro exactly as if typed at the command line. Always prefix `!` (cancel) and `-` (no dialog): + +```python +rs.Command("! _-Line 0,0,0 10,0,0", echo=False) +``` diff --git a/skills/rhino3d-scripts/references/vbscript-quirks.md b/skills/rhino3d-scripts/references/vbscript-quirks.md new file mode 100644 index 00000000..e08729e7 --- /dev/null +++ b/skills/rhino3d-scripts/references/vbscript-quirks.md @@ -0,0 +1,112 @@ +# VBScript Quirks for RhinoScript + +Things that bite when writing `.rvb` / `.vbs` files and aren’t obvious to anyone whose mental model is C-family or Python. + +## Always Start With `Option Explicit` + +Without it, mistyping a variable name silently creates a new `Variant` set to `Empty`. Every `.rvb` file should begin: + +```vbscript +Option Explicit +``` + +## No Block Scope + +All `Dim` declarations inside a `Sub`/`Function` are hoisted to the top. A `Dim` inside an `If` block is visible after the `If` ends. Loop counters survive the loop. + +## `Nothing` vs `Empty` vs `Null` + +| Sentinel | Test with | Meaning | +|---|---|---| +| `Empty` | `IsEmpty(x)` | `Dim`’d but never assigned | +| `Null` | `IsNull(x)` | Explicit “no value” — what `Rhino.GetObject` returns on cancel | +| `Nothing` | `x Is Nothing` | An **object** reference that points to nothing — only for `Set` variables | + +Wrong sentinel → silently false. + +## Parentheses Change Semantics + +```vbscript +Foo a, b ' Call a Sub or Function (return value discarded) +Call Foo(a, b) ' Call a Sub or Function (return value discarded) +x = Foo(a, b) ' Call a Function and capture the return +Foo(a, b) ' SYNTAX ERROR for multi-arg subs + +Foo(x) ' Calls Foo passing x BY VALUE, even if Foo declares ByRef +Foo x ' Honors Foo's ByRef declaration +``` + +If a Sub modifies its argument and your change isn’t taking effect — you wrapped the argument in parentheses. + +## `ByRef` Is the Default + +Unlike most languages, VBScript passes arguments **by reference by default**. Functions can mutate their callers’ variables. Be explicit: + +```vbscript +Sub Increment(ByRef n) + n = n + 1 +End Sub +``` + +## Arrays Are 0-Based But Have `UBound`, Not `Length` + +```vbscript +Dim arr(2) ' Three elements: arr(0), arr(1), arr(2) +For i = 0 To UBound(arr) + arr(i) = i * 10 +Next +``` + +`Dim arr(n)` creates `n+1` elements. `ReDim Preserve arr(newSize)` resizes (only the last dimension of a multi-dim array). + +## `Set` Is Required for Object Assignment + +```vbscript +Set fso = CreateObject("Scripting.FileSystemObject") ' correct +fso = CreateObject("Scripting.FileSystemObject") ' RUNTIME ERROR +``` + +Any time the right-hand side is an object (COM object, RegExp, Dictionary), you must use `Set`. + +## Error Handling Is Manual + +```vbscript +On Error Resume Next +Rhino.AddCircle Array(0,0,0), -1 +If Err.Number <> 0 Then + Rhino.Print "Failed: " & Err.Description + Err.Clear +End If +On Error GoTo 0 ' Restore normal error behavior +``` + +`On Error Resume Next` suppresses **all** errors until `On Error GoTo 0`. Forgetting to restore is a common bug. + +## Points Are 3-Element Arrays + +Rhino expects `Array(x, y, z)`. A 2-element array (`Array(x, y)`) raises a type-mismatch error. + +```vbscript +Dim pt +pt = Array(1.0, 2.0, 3.0) +Rhino.AddPoint pt +``` + +## String Concatenation Uses `&`, Not `+` + +`+` on strings works only if **both** sides are strings. If one side is a number, `+` does numeric addition and throws a type-mismatch. Always use `&`: + +```vbscript +Rhino.Print "Count: " & n +``` + +## `For Each` Needs a `Variant` + +```vbscript +Dim item +For Each item In someCollection + ' ... +Next +``` + +The loop variable must be `Variant`. You cannot `Dim item As Long` (VBScript has no typed `Dim`).