Jump to content

The VectorScript Advisor: What do I do with a VectorScript, anyway?

Recommended Posts

  • Vectorworks, Inc Employee

I've often seen newer VectorWorks users (or even experienced ones) post questions like,

"These VectorScripts look like they do really useful things, but how the heck do I use them?"

Well, no one has time to read the manual to expose a completely new aspect of the program, so in this post I'll try and condense it a bit. There are essentially 3 ways to use a VectorScript from within VectorWorks:

  • Run it using the "Run VectorScript..." command;
  • Create a document script and run it from a script palette;
  • Turn it into a plug-in menu command, or VSM;

Let's address these methods one by one, but before we do, let's make sure everybody agrees on what "a VectorScript" is. A VectorScript (VS hereafter) is a text listing, and it's really not picky about formatting or capitalization. Some people (like me) use a lot of tab-indenting to make the VS easier to read by other programmers, but VectorWorks really doesn't care about this when it's running a VS. What you do need to know is that a VS always starts with a PROCEDURE call and ends with a RUN call. So, your VS listing (which will become your text file or document script or whatever below) will always look like this:

PROCEDURE My_Script_Name_123;

(followed by a whole lot of programmer-ese, sometimes hundreds of lines!, finished up with)


It is these two lines of code (and of course everything in between) that constitutes "a VectorScript", and this is what needs to be cut-and-pasted from these forum pages into a text file or VS Editor window to make it into a useable form.

Now, let's look at the three methods enumerated above:


Run a VectorScript using "Run VectorScript..."

This one is the easiest. Copy the VS from where you got it, and paste it into a file using a text editor. Instead of saving it with a .TXT filename extension, save it with a .VS extension. Put it somewhere in your computer's file system where you won't lose it. When you want to use the script, just run Tools:Scripts:Run VectorScript... and you will see a standard open dialog. Find your script and click the Open button at the bottom of the dialog. The script will run.

This method has the advantage of being easy and quick, and is the easy way to make a VS available to any VectorWorks file.

Create a document script and run it from a script palette

This method creates a script that is saved with a particular VectorWorks file. This can be useful is your script has been customized to work with just that file, or if you need the script to properly manage the file and you need to send the file to someone across the country, say.

To handle a script this way, use the Resource Browser and choose "VectorScript..." off the "New Resources in [filename]" menu. If you haven't already got a Script Palette created, VectorWorks will create one for you called "Palette-1" by default. You'll see a small "Assign Name" dialog asking you to name the script and when you click OK, you'll see the VectorScript Editor window. This is essentally a very simple text editor window. So, copy your script from wherever and paste it here. Click OK, and and the VS Editor window will close and you'll see a new "Script palette" which is just a small palette with your script name in it. Just double-click the script name to run it. You can have as many scripts as you want in a single script palette.

Turn a VS into a plug-in menu command

This method, which is somewhat more elaborate, allows you to add a script permanently to your workspace as a menu command. Use this when you have a script that you use all the time, one that you want to add a keyboard shortcut for.

To use this method, run the Tools:Scripts:Vectorscript Plug-in Editor... command. You'll see the VectorScript Plug-in Editor window. Click New. You'll now see the Assign Name dialog for plug-ins. Give your object a unique name and highlight the "Command" radio button if it's not already chosen. Click OK. You'll be returned to the main VectorScript Plug-in Editor window and the name you just entered will be highlighted in the list. Click the Script... button. You'll see the VectorScript Editor window (just as in the second method). Copy your script from wherever and paste it here. Click OK. Now you can optionally give this command a category using the "Category" button on the middle-right of the dialog. Click OK in the VectorScript Plug-in Editor window and you're done.

What you've just done is create a "VSM" file (a VectorScript Menu command plug-in) in your Plug-ins folder in your User Preferences folder. (Exactly where this folder is located is dependent on whether you're on a Mac or Windows machine, but it's where all your preferences are kept, also.)

Now that you've created this plug-in, you can add it to your workspace and assign it to a keyboard shortcut using the Workspace Editor command, just as you would any other command. It will show up in the Menus tab of the Workspace editor under the category you gave it (if any) in the VectorScript Plug-in Editor window. If you didn't categorize it, it will show up under the "Miscellaneous" category in the list at left.


OK, that's about it. Use your VectorScripts in good health!

  • Like 4
Link to comment

A good article, Robert!

Those who intend (or fear being compelled) to do even slightly complex scripts would be well advised to adopt a structured way of programming from the outset.

This includes also standardisation of common variable, constant and subroutine names.

With this approach, one can easily redeploy functions and procedures, ie. copy and paste them (or even establish 7 or 8 large libraries used via $INCLUDE).

Like this:

PROCEDURE My_Script_Name_123;

{ declarations }





{ code }




{ code }


BEGIN ( main }

{ code }

abc; { call to subroutine }

{code }

bcd; { call to subroutine }

{ code }



VS is based on Pascal, so textbooks on Pascal can be useful. The good doctor Wirth developed Pascal to encourage structured programming. http://en.wikipedia.org/wiki/Pascal_(programming_language)

Link to comment

This seems like a good place to post a valuable bit of advice I got from a programmer friend when I was starting. It's a good idea to give your variables,constants and procedures clearly descriptive names.

When I started I had the false notion that shorter names would somehow be more efficient, possibly because it means less typing. A few extra keystrokes are pretty insignificant to writing and running the script, but can make it far easier to understand and maintain.

Example: I'm currently re-working something I wrote years ago. I'm looking at things like 'wrknit' and scratching my head. What is that? What does it do? Two more keystrokes and I would've had 'WorkUnit' and that section would read like a book.

Another comment for beginners: It may not be obvious what the characters { } do in Petri's example above (and elsewhere). These make the words enclosed by them invisible to the vectorscript compiler. Without them all kinds of errors would be generated. Some of us use them to add 'comments' into the script to help make it clear what the different lines and sections are supposed to be doing.

They are also used to "comment out" sections or lines of code that seem to be behaving badly, or producing un-intended behavior. Then you can see what happens if that stuff is gone. It's one of the basic tools of de-bugging and script development, along with "messaging out".

And what is messaging out? In re-working my script I may want to verify that WorkUnit is carrying the data it should after it goes thru some math in the script. If I place Message(WorkUnit) at the appropriate spot or spots, a message will appear on screen displaying that value. After I'm satisfied I delete that bit.


Charles Croft

  • Like 2
Link to comment
  • 6 years later...
  • Vectorworks, Inc Employee

It would still apply, yes, Python was added as another language supported for scripting rather than a replacement for Vectorscript.

I have not heard of plans to remove the original language at all. However as far as which language to start with from scratch, most likely the newer language would make the most sense.

Link to comment
  • 1 year later...

Now that Marionette is going to be introduced so that it is easier for the non-programmers to create scripts does this still apply?

The reason I am asking is that Vectorscript is fully controlled by Vectorworks while Python probably is not so it seems that if functions are dropped by the community in Python the chance for compatibility issues in the future is bigger than with Vectorscript.

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...