Jump to content

Vectorscript Objects

Recommended Posts

How can I create a parametric object with Vectorscript?.
For example, I want to create a rectangle that has a certain figure inside but which can use that figure as a symbol and which can change the parameters in the object information palette.

I want to create this figure as a symbol and have parametric properties to change each point independently.




Link to comment

You’ll need to start by creating a parametric object in the plug-in editor in the tools menu.

You could create a rectangular object, that’s one of the options. In the same plug-in editor you can also add parameters and add the script. That can be Vectorscript or Python.

you can also import an external file into that script. That external file can then hold the main part of the script.

Link to comment

Vectorscript, which is itself based on an old language called Pascal, can be a bit obtuse (the biggest hurdle I had coming from Java and Python was figuring out how to properly use handles), but there are a lot of code examples that can be found on the online wiki as well as the offline Function Reference.  On a Windows machine, that function reference is stored in C:\Program Files\Vectorworks ####\VW Help\Script Reference\ScriptFunctionReference.html.  I assume it's stored in a similar manner within the application folder on a Mac.  While I'm working on scripts, I always have it open somewhere, usually on a second monitor.  It's faster to navigate than the online wiki, and you don't need a connection for it to work.


For Python, there are a ton of online resources to teach yourself the language, but the implementation in Vectorworks is a bit tricky.  You will still need to use the commands found in the Function Reference to interact with VW, but you will gain far greater control in terms of how you handle data.  I learned Python several years before it was available in Vectorworks, and by the time they implemented it, I was more comfortable with Vectorscript, so that's primarily what I work in.


If you do want to go through the process of learning Vectorscript, an excellent starting point would be the Vectorscript Language Guide, which used to be part of the main VW help but has since moved off to this separate document.  It's what I used to teach myself back in 2010, and it's pretty easy to follow as far as these things go.

Link to comment

@Pat Stanford No kidding, Python can be a huge pain to debug because of the incredible freedom it gives you and it being a run-time language.  For all its rigid quirks and archaic rules, Vectorscript is at least pretty forgiving and easy to debug (as long as you don't cause a memory leak leaving out a parenthesis in a ForEachObject call...), especially after 2016 when they finally added in line numbers to the IDE.


@Arielus Putting "Vectorscript" into the search field in YouTube does yield some results, but there doesn't appear to be a full tutorial.  Coding in general is something that I think video tutorials are not super great at, as scripting is a written medium as opposed to a visual one.  If you are looking for a more visual focused method of object creation, I would suggest trying out Marionette, of which there are several training videos from Vectorworks (like this one here).  I find Marionette clunky and slow since I can type much faster than clicking and dragging variables around, and Marionette objects run slower than scripted plug-in objects (though this did start getting much better starting in VW2020).


I think jumping in to Vectorscript without any coding experience might be a bit daunting, especially because of its relative lack of "beginner friendly" documentation.  I would suggest looking into an online course for a more common language to learn the basics of coding such as C, C#, or Java.  Python is a tricky first language because of the way it "bends" a lot of the rules of programming.  It was designed as a language that could be picked up in a day with any experience in coding, but it could teach you some bad habits that would hamper you in working with other languages.

Link to comment

For a relatively high level explanation of Vectorscript, see this thread in the Resource Share - Vectorscript forum.


Resource Share is mostly information carried forward from the older version of the forum, but there are a lot of good scripts there.


I try to comment most of the scripts I post to make them understandable and as a learning tool. @Jesse Cogswell@michaelk and many others are all too willing to help with the learning process.


My personal opinion is that Marionette is the best tool to make a parameterized object in VW if you don't have scripting experience. and Vector(Python)script is best if you want to do data manipulation on existing objects. Marionette takes away all of the complexity of getting and using data entered in the OIP that ends up being a lot of the script in most Vectorscript Parameterized objects.


@Arielusfor yoru object above if you are always making a rectangle, you really only need three points. Bottom Left, Top Right, and the center point. I would probably start with a really simple version that is a fixed size rectangle and only work on the code to make the internal polygon. Once I got that working I would then go back and add the code to allow the change in the rectangle size.


Ask again when you need more help.

Link to comment

Perhaps you can look around some more. There is a lot of information available already. It's best for your object to make it with Marionette you can start to look at the Vectorworks YouTube page. Especially the playlist. 


Marionette Mondays playlist:



Marionette tutorials playlist: 



Then there is the Marionette galleryhttps://forum.vectorworks.net/index.php?/files/


And not to forget we have the Vectorworks University with loads of video's: https://university.vectorworks.net/course/index.php?mycourses=0&tagfilter[category]=35&tagfilter[type]=0&tagfilter[difficulty]=0&categorysort=default&mycourses=0&search=Marionette&langfilter[]=0#coursestab


I advise you to check these places first next time you looking for information.


Edited by MarcelP102
Link to comment
  • 2 months later...

@Jesse Cogswell Excellent crash course in Vectorscript; thank you for putting this together.  I stumbled across it out of an extreme frustration with Marionette's instability and in search of an alternative to Marionette.  I was able to take your script, add it as a plug-in, and successfully make some changes (such as adding another point and adjusting the colors).  Any particular reason you alternately use numbers and letters to identify what appear to be the same points?  When I changed all of the numbers for points in your script to their corresponding letters, the script continued to work fine.


Looking at some scripts gave me some ideas that I think I've successfully implemented into Marionette so, between that and yet another Marionette work around or two, I'm continuing with Marionette... at least for now.  I can see that it would take a huge time investment to become proficient with Vectorscript or Python.  In the meantime, again, thank you for your crash course!          

Link to comment

@willofmaine The reason I alternate between letters and numbers for points in this example is more or less down to how I name and handle variable names between formal declarations (declared in the VAR block of code) versus variables named in the PROCEDURE/FUNCTION definition.  Almost always, I will name points with capital letters, both because of ease of typing (handling points requires a lot of lines of code since each X, Y, and Z setting requires its own line), and because of how I learned geometry in high school.  That all being said, because of the way Vectorscript handles PROCEDURE/FUNCTION definition, you need to declare what variables and in what order the constructor will be looking for as "arguments."  While you technically can pass in the same global variables into the constructor, it's best practice to keep them as local variables within the definition (allowing for better modularity of code, even if Vectorscript really has no way of sharing code from script to script).  I'm often lazy when dealing with constructor arguments, so I'll often just name them as the variable type followed by a number (s1,s2,s3 for STRINGs; h1,h2,h3 for HANDLEs; i1,i2,i3 for INTEGERs; p1,p2,p3 for POINTs) rather than giving each a more unique name that I have to remember and not conflict with an existing variable name.


At the end of the day, Vectorscript or Python don't really care what you name your variables as long as they don't start with a numeral, and that they aren't the same name as an existing function or special word (can't name a variable var because of the VAR special word, or count because of the existing Count() function).  Special words should be obvious as most IDEs will color them separately to highlight them, and naming a variable a function will throw an error in the compiler (or during runtime with Python).


I'm glad that you got some use out of the crash course.  Learning a programming language is definitely something I'd recommend, and the hardest language to learn is the first.  Once you learn one language, a lot of the ideas will translate to another, then it's a matter of learning syntax and flow.  Python is at once a wonderful language to start with (it's used pretty much everywhere nowadays, there are a TON of resources to learn it from, and, as far as programming languages go, it's really simple to learn), but also does so many things for you that it can be hard to transition to another language.  Learning Vectorscript as your first language will also be challenging just because your resources are restricted to this forum and the developer wiki, as Pascal hasn't been a super relevant language in the last 25 years, so there are far fewer online resources.  But at the same time, the Python implementation in VW is built on the Vectorscript function library, so knowing Vectorscript makes scripting in Python for VW so much easier.


I'm pretty bummed with how Marionette has gone.  When they first debuted it in 2016, I was really excited about the possibilities.  It was even the very first thing I played with in VW2016, but it's very clunky as far as visual scripting goes, and I've always found it sluggish to both program in and the performance of Marionette objects.  And overall, its implementation hasn't changed much since its inclusion, even in VW2022 Marionette objects are sluggish (though they take up far less in terms of file size, so that's nice at least).  My twin brother works in the digital animation industry and uses node-based visual scripting in Blender and XSI SoftImage and was horrified when I showed him how it works in Vectorworks.


Best of luck continuing your Marionette and scripting journey.  Please feel free to let me know if you have any further questions.

  • Like 1
Link to comment

@Jesse Cogswell Ah... so there is a method to your madness.  I'm not surprised, really... And again, thank you for taking the time to explain, and for your thoughts on scripting and Marionette.  Like you, I was very excited when Marionette was introduced (I hadn't ever seen graphic scripting before), and I whole-heartedly embraced it.  But at least two, maybe three times in the past I've abandoned Marionette, each time swearing to never return.  But I just couldn't let it go; I've created a sizable collection of extremely useful (when they work) Marionette objects, all well worth the time invested in creating them (excluding the time lost fighting with their many issues).  Even though I've got my latest Marionette working (at least for the moment...), I think I'll actually change my mind and follow your recommendation of learning a programming language; at least now I can do it at my own pace, maybe so that the next time Marionette's disagreeable I'll have a viable alternative in the works...


So the question is, which language?  @Pat Stanford had suggested Python as a first language, though he also complained about its being "white space delimited."  I can find plenty on the Web for Python, but nothing specifically for Python within Vectorworks... and the two implementations look different to me.  So, at least for starters, I ended up pursuing Vectorscript, thanks to your crash course.  And looking just now, I can't seem to find a simple Python-based plug-in object that I could try and reverse-engineer from; everything seems to be Vectorscript.  Do you by any chance have, or know of, a crash course in Python??



Link to comment

Python is probably the easier language to learn, and it comes with the added benefit of being applicable to Marionette since the nodes use Python to determine their operation.  There are also a TON of classes online that teach Python.  Don't be worried too much about it being white space delimited, it just means that you have to be very strict about how you use tabs and spaces or the code won't work properly.  Python does get a little tricky in this regard, as its not a compiled language like Vectorscript, so there's no error checking until it's running, and it can be tricky tracking down what is causing the code to break.


Unfortunately, I'm not too familiar with Python's operation in Vectorworks.  I learned Python on my own back in 2010, but haven't really touched it since aside from editing a couple of Marionette nodes.  By the time it was added to Vectorworks (2015 maybe?), I was very comfortable with Vectorscript and didn't have much need to switch.  I am working on a project to add copy protection into some of my plug-ins that will require Python in order to ping an online database (there doesn't seem to be any way to do this with Vectorscript natively), and another project to ease the update process so that it's no longer manual (file operations in Vectorscript are strictly limited to text files and are severely limited on what you can actually do to files).  Python opens up a whole world of possibilities outside of the scope of Vectorscript because of its ability to import libraries.  My current plan is to script in Vectorscript and then use PythonBeginContext to script in just what I need Python to do.


The thing that makes Python a little harder to use in Vectorworks is that you are still limited to the Vectorscript function library to actually manipulate Vectorworks.  Most of the time, it's taking the Vectorscript function and adding "vs." to the beginning of it.  So, creating a rectangle in Vectorscript would look like Rect(p1.x,p1.y,p2.x,p2.y) and would look like vs.Rect(p1,p2) in Python.


The other thing to keep in mind is about how Vectorscript and Python handle variables.  Both are "typed" languages, meaning each variable has a defined variable type.  What makes them different from each other is that VS is "statically typed" and Python is "dynamically typed."  In VS, every variable MUST be defined as a variable type (string, integer, real, etc) and can only ever be that type.  In Python, you can define a variable without assigning a type, Python will do that for you.  Variables are also able to change their type within the code.  So you can have a variable start as an integer (whole number only), then change to a floating point value (decimal number) when needed.  This makes the language much more flexible, but also potentially dangerous if your code is sloppy.


It also makes the code slower to operate, in that the "higher level" operations that the code does for you comes at the cost of computation time.  While this definitely won't matter much in the scheme of Vectorworks plug-ins, it does matter when writing complex programs like mathematical solvers.  Python is considered to be a "slow" running language that balances out by being very quick to write.  If the programmer's time is more valuable than the computational time, then Python is the way to go.  If you need the program to be snappy and can afford the cost of competent programmers, then it's best to use something like C++ which has virtually no hand-holding (manual memory management, garbage collection, etc), but is basically one step removed from assembly code and super fast to run.  If you end up really getting into the weeds, the absolute best way to write plug-ins for VW would be to write in C++ using the SDK (software development kit) since you would have access to basically everything Vectorworks can do, but C++ is a much harder language to learn and definitely not what I would try to learn first.

Link to comment

Okay!  Sounds like I'll skip the C++ (not that I was considering it!...) and see what I can figure out with Python.  And to that end, maybe what I'll do for starters is just forget about Vectorworks altogether and go learn some "regular" Python (by downloading the Python Interpreter and that "Mu" thing and whatever else).  And then, just maybe, hopefully, the incorporation of Python into Vectorworks might make more sense to me.  In the meantime, thank you for all of that information!  Some of which is very helpful in choosing to tackle Python, and some of which I suspect I won't fully appreciate until I've spent some time with scripting.  I'm looking forward to seeing what I can figure out... Thank you!! 

Link to comment

Join the conversation

You can post now and register later. If you have an account, sign in now to post with your account.
Note: Your post will require moderator approval before it will be visible.

Reply to this topic...

×   Pasted as rich text.   Restore formatting

  Only 75 emoji are allowed.

×   Your link has been automatically embedded.   Display as a link instead

×   Your previous content has been restored.   Clear editor

×   You cannot paste images directly. Upload or insert images from URL.

  • Create New...