Virtools Tutorials, Tips and Tricks

Recently I was asked how to use global variables inside global functions using VSL, one of 3DVIA Virtools built-in scripting languages.

In VSL you can share a variable across diferent "Run VSL" BuildingBlocks by using the keyword "shared". For example

Besides using VSL in BBs or actionscripts, you can also create "global" VSL scripts. These are automatically included. The things is that you can not use the shared keyword inside global scripts. So if you want to modify shared variables inside global functions, one workaround is to use parameter-objects.

Basically it's a struct containing variables you like to share. Either one struct for all or split your variables by context into different structs. This user defined structure makes passing them to functions much easier. Also less code changes are required when adding more data.

Above you see the definition and how it's used as input parameter of a global function. This works because it's passed by reference and not as value (/copy). This way you can modify shared variables even inside global functions. Here is how it could look like inside a VSL BB that calls the global function:

I hope this will help a few more people. If it's not clear, let me know.

For a couple of years now, I am "misusing" Characters for a lot more than "just characters". For those that don't use Virtools, a Character Entity is a 3D entity that has "bodyparts" entities. A bodypart can be a bone, a dummy or a an entity with a (skinned) mesh. You can also add all kind of non bodyparts to the hierarchy.

The interesting aspect is that the whole combination can be treated as one. In the 3D layout window, you usually pick the character entity and thus you translate the complete set. Moreover there is a character parameter type, thus you can search, store, hide etc the whole complex as one.

Office chairs, where you want to be able to change the height or rotate the seat, are a simple example.

Last year I had a combo of particles systems that I wanted to treat as one unit. Easier as asset and easier to create, duplicates etc. Thus I wanted them to be part of a Character.

(Edit: the following passage is not entirely correct, see notice in bold that follows)

The first thing you may notice is you can't easily create any characters or bodyparts inside the Virtools authoring system. Even via the scripting language (VSL) one is not able to create such objects.

Missing VSL bindings is still a problem in Virtools (although things got better). We have a custom DLL where we do our own bindings in these cases, but I wish I would not have to waste my time on this. After I was able to create Characters and bodyparts via VSL I saw that the Level Manager didn't update it's character content. I don't know yet what kind of notification it requires but saving and reloading the file (or asset) fixes the problem.

( EDIT:  as pointed out by Julien in the comments, you actually can create characters and bodyparts using bc.CreateObject – just like in the SDK. There's are only no shortcut bindings like bc.CreateEntity3D )

On my first iteration I simply added the particles system dummies to the character hierarchy, but they also were listed separately when loading them at runtime. Unfortunately you can't attach the particle system components (building blocks) onto bodyparts but only onto so called "3D frames" which are the 3d dummies (/gizmos) of Virtools.

"Hey wait!" came into my mind – 3d dummies in Virtools are 3d entities with an additional flag and bodyparts are special 3d entities. So I did the hack: added the flag to my bodyparts and suddenly they accepted the particle system buildings blocks!

I wrote me a little action script that creates a "particle character" from a set of distinct particles systems. I have no idea how solid this is, but so far no complains from the customer! Hehehe …


It makes it much easier to move, load, store particle-system combos (only textures need to be selected manually in some cases).

Friday I was composing some object shaders and integrated them into the project. At some point we realized that under-water objects where reflected as they were above the water although I was using clipping panes. I thought I screwed up something but an idea made me check everything without the shaders and I found the trouble maker: the default shader of virtools is setting ClipPlaneEnable to zero! 


After the initial shock, I thought: interesting, can it entirely be setup and used inside the HLSL technique definitions? Soon I dropped that idea, because I would have to do technique-switching and that requires manual bookkeeping as Virtools offers no help with that. So how could I get back my correct reflections?

I thought about an old workaround I did somewhen in end 2006 or early 2007 but for this scenario it wouldn't work. This time I really would need some kind of "texkill" instruction that I did not found back then. And you know what? The HLSL counterpart is


Probably you all already know about that, but for me it's my new best "HLSL  friend"! :)

All fine now 8)

(Btw. in regards to the default shader, it might be a better idea to omit that state overwrite. Don't know how this is helpful in the way it is right now. )

I few months ago I bought me a new computer. A nice quad PC. Something I wasn't happy about was that it was bundled with VISTA. But then I thought it would be a good time to re-look at VISTA and learn all its positive and negatives sides, besides that my machine has 4 Gig of RAM which won't be used under XP.

My first contact was over one and half years ago and I had troubles setting up a networking application on it. So my my first contact wasn't positive. And now?

VISTA in a Home Network

Microsoft claims that it always look what the trends will be in future and develop for that. Apparently they didn't foresee that people will have networks at home with mixed OSes. In my case I have machines with XP, VISTA and OS X in the network. So first time I wanted to access the XP machine, I get a pop-up dialog saying that there are incompatible devices in the network. So I got a blank network page and no further information. After some research I found that I have to patch XP.

In addition to that, for being able to access shared folders of OSX, I had to modify the registry. Establishing access to the Internet was painless but beside this, VISTA Home Premium (!) failed to cooperate with my other machines out-of-the-box.

Network Map

Vista's network map also shows router devices. 

System RAM and 32 bit VISTA  

Well, officially it says 4 GB RAM is supported. But I think it's misleading. You need to subtract the amount of VRAM your GFX-card owns. Mine has 512 MB, so the task-manager says that 3581 MB of physical system memory is available. With 1 Gig of VRAM you probably only will be able to address 3 Gigs of your system RAM. At least I think so, but this articles says the address-space is needed by the hard-disks, so maybe the VRAM hasn't this kind of impact …

At a given moment I had to import some CAD data and needed the maximum of my RAM to be available. So I checked my system and strangely most of my memory was used. This is due Vista's SuperFetch, which preloads commonly used applications and data. This is also one of the reasons why on start-up it may take a while until the hard disk stops turning.  Basically this seems to be a nice feature, but for that situation, where I needed the be sure about memory usage, I turned it off via the registry and since then not back on. I think apps now take a little while longer to load but the system-startup is faster. Probably I'll turn it back on one day in order to observe the differences further.

Another aspect was that aprox 2 Gigs are reserved for applications and another 2 Gigs for the kernel. This can be altered using this command:

bcdedit /set increaseuserva 3072

It indeed increased the memory used by the application – it didn't reach 3 Gigs but was more like 2.8 or so. But now the kernel has less space and it might produce side-effects if drivers (like for a 1 Gig VRam Gfx card) assume 2 Gigs. Maybe I'll turn it later back to default of 2048 using.

bcdedit /set increaseuserva

Visual Studio 2003 and Virtools 4.0

Officially Visual Studio .Net 2003 is not supported on Vista. I turned Vista's 'User Access Control' (short UAE) off and it seems to work fine so far, including debugging. Something that does not work are the Virtools 4.0/3.5 wizards. Virtools 4.0 works fine except that the font/typo is kinda blurry. There is some kind of red ghosting it seems – not sure if you can see it on the left screenshot. This must have to do with the font anti-aliasing. Vista uses by default ClearType. If one switches to standard, as shown on the right picture, then the font in Virtools is very nice but then it becomes blurry in other places of Vista. For example window captions.

Virtools 4.0 under Vista   Two methods of font AA in Vista

I don't know how it's in Virtools 4.1 – maybe it's OK there. Otherwise our option is only to switch between both modes for long sessions.

Quick Launch ain't real Stacklets?

In my quick launch toolbar I only have a few common shortcuts (browser, eMail, winamp, trillian, total commander). I use additional, collapsed  shortcut bars for i.e. frequently used development tools like PSPad, Visual Studio and Virtools. There are some inconvenient aspects to this: the button is pretty small as the toolbar name doesn't act as button and under Vista icons become visible when the area with network and active app-icons gets collapsed.

toolbar close to system tray - inconsitence

Currently I am trying something different: RocketDock in combination with the Stacks Docklet plugin, both are free. For the stacklet icons I use some free-ones that can be found on the web like here, here or here. I have it at top of my desktop, I hope it won't disturb me too much. I think I still would prefer to have it inside the taskbar itself!

RocketDock with Stacks Docklet

VISTA Security

The vista firewall doesn't really prevent outgoing traffic from applications. It seems much more configurable than the one that comes with XP but it may give a false sense of security. Luckily since recently my preferred personal firewall is also available for Vista. I think this, in combination with the free AVG for personal use, will provide a better protection.

VISTA Theme Style

The task back is 'back in black'. Unless you use the aero theme where you can tint it and, in combination of transparency, mix it with the desktop background image, there is no real control about it's colour. I am no fan of having it in black and disappointed of the lack of choice. Although VISTA has theming it seems locked (for OEM partners?) and you are still required to use 3rd party solutions.

Vista Start Menu

Thestart menu now contain the program directory instead of displaying them in a pop-up. The named reason for this is that people tend to have that menu as large as the whole screen with plenty of installed programs. Now you start with the root dir as list and you click into subfolders. I don't like it because it requires additional clicking. MS probably count on the new indexed searching and the field where you simply type in the first letters to filter the choose. I disabled indexing because having the harddisk rotating all the time disturbed me. In addition to that I organize my start menu in major categories like: 2D, 3D, video, Web, Tools, Games etc. I don't like if installers doesn't give me the option to choose the exact location but in that case it doesn't prevent me from moving the shortcuts afterwards which of course gives me stuff to cleanup manually after an uninstall.  And that's where I think MS should have done something more sensible like providing some more standard categories (including API) and tracking, when somebody manually moves shortcuts, for the uninstallers.

On the right side there are some common shortcuts, but some are as sub-menus and some simply as buttons. As you can see in the screenshot, I changed most of them to submenus so I don't have to click on them and for that I don't get an additional window. A good thing would have been if even in sub-menu mode, those items are click-able. another annoying thing is speed and consistency. They often pop-up slowly and sometimes not at all. also on the top-righ side there is an icon that fades into another according the menu item under the mouse. For me it has no real benefit and it even doesn't look better. Sometimes one gets the impression that the slow pop-up are related to the icon-fade but I think it's not the case.

Something else that looks strange is the main menu bar. It has some glossy gradient and somehow it looks misplaced in some standard applications. Below in the article there's a screenshot of the resource manager and it gives an impression about what I mean. In some other applications it looks even worse. Also the progress bars are animated – an 'energy impulse' is going from left to right from time to time. In one case I had a window with a couple of these at 100% and the pulsation felt pretty distracting.

Games section

There's a new window where games are listed that registered themselves there via a new API. It shall help to protect kids so they can only play games fitting their age etc. What I miss is a deinstall item in the context-menu. I often play game-demos because they are time-limited and thus a bit less a time-sink 


 So uninstalling demos is something I do frequently. There are also a few new games like chess and InkBall. I really like InkBall – played it once for a while – a nice casual game where you draw obstacles using a pen to modify trajectories of balls in order to make them roll in holes.


Positive aspects of Vista (partly)


There are some things I like in Vista. Although I don't use the explorer much, I really like the way one can choose a new dir on any hierarchical level of the current directory patch. You can also add commonly used folders in the top-left corner as favorites. In some situations I saw a 'directory' pointing to recently used directories which could be VERY handy but unfortunately in many applications this is not available inside the "open file" dialogs. That would have been a really good improvement! 3ds max has such a directory-history but unfortunately also only in one of their open-file dialogs and not everywhere.

Explorer Adress Dropdowns

Resource Manager

Something really good is the new resource manager. That's something I always was looking for, for that the system becomes more transparent. One day I was listing to some music while chilling but the harddisk didn't stop working and working … With the resource manager, which launch button is badly hidden in the task manager, I was able to see what process was using intensively the disk and on what files! I found that Vista did some random backup of my system.

Very useful resource monitor Not so accessible ressource monitor

This surprises me a bit because I thought this wasn't a Home Premium feature. I turned it off and the computer became quiet. This feature is called 'shadow copy' and although using Vista Home Premium, you can't use it to restore parts of the system by intention, it is used by other services and the Window updater. People recommend to not turn it off.

Voice Recognition and TTS

The Voice recognition engine is much better which is really interesting. But when I tried to dictate an eMail in thunderbird with it, it showed that it still has some way to go. The text area of thunderbird is not recognized and thus a global, less user-friendly mode needs to be used.

Also the TTS voice sounds better, but although I have a german Vista version, it's the english voice and only the english one without possibility to download additional languages. 

Windows Sidebar

I like the clock and calendar of
the sidebar because of it's bigger size, but beside this I haven't really used it – maybe notes. Weather and gadgets like this doesn't interest me and for RSS I have better tools. Do you use it?

Additional Tools

Vista comes with some useful tools like snipping (selecting an area for a screenshot), Zoom, Notes etc. Unfortunately all of them have their usability drawbacks. It clearly shows that MS has more techies (coders) and less designers – OR – it's their strategy to only provide basic, not- designed  tools (like MS Paint). I don't know.

Notice App


Overall the user experience could be much better. Microsoft certainly put a lot of work into this but failed on some important aspects in the domain of usability. Vista has a pretty bad reputation, some people like it but too many aren't happy with it. I think Microsoft is aware of this – even if they deny – as they already announced Windows 7 (MS guys went like this: "No we don't talk about the next windows which is called Windows 7… and btw. it has multi-touch support built-in and maybe it comes sooner as expected, but you know we don't talk about it").

Wink Tongue out

I would have loved if they would have improved Vista over a couple of iterations via service packs. But I guess from the the business side and marketing side they wanted to get rid of the bad reputation of Vista and thus the 7 instead of something in the line of XP or Vista. But I am guessing here.

I think a key feature of Windows should be easy customization. The middle between OS X (few choices)  and Linux (plenty choices). A good approach would have been to introduce some Target-Audience profiles. Some people just want to use their computer, some want it to tweak a bit and others want as much of transparency and control as possible while keeping the GUI-approach. It's a bit like complex DDC tools: they have different layouts – i.e. in 3D for doing light setups, rigging, modeling etc. 

I know that people like Joel think that choices = headaches but I already didn't agree back then when he complained about the shutdown choice in Vista. Too many choices are bad but not enough choices is bad too. It really depends on the personal preference. There's a good reason why GUI customization in complex applications like 3ds max, Silo, Maya or Modo is very important. Besides saving every clicks and distances, personal tastes do play a role for productivity!

What if Vista would have come with theme-creation tools and a community webplatform for sharing and (like Stardock does)? Instead they locked that feature.

I also miss built-it multi-desktop – the first time I experienced it was like 10 years ago on an Irix machine. Alreadythere I wondered why it's not available in windows. Well nowadays there are but it's 3rd party and most of them only deal with windows and not icons on the desktop itself. I tend to have too much icons on the desktop, so multiple desktops probably would help 


I already mentioned stacking link-shortcut lists for the taskbar. It's like an enhanced quick-toolbar. The new Mac OS X has it and it's nothing revolutionary but it totally makes sense.

Well, this blog post became pretty long. I think there's more to tell but that's it for now. Cheers Cool

p.s.  Some other recent rants about Vista on blog I read: Steve's BlackAndWhite and Aras's The Problem Of Vista

You have a complex shader with tons of parameters and you tweak and tweak and tweak …. and somehow an older version might have been better – or you want to compare multiple versions? Of course you could implement something that does store the values etc but here is a simple – not perfect – workaround for this kind of situation:

For each 'tweaked' version, save your material as NMO into the materials folder of your resource database. Ok, now you can drag and drop the material onto your object or level … what do you say? "It's not working!" Yep, it keeps the old shader values … what you have to do to get the ones from the saved NMO is: each time before dragging in the new material NMO, you go into the material and change the shader to "– None –"- Then when you drag in the new material, you'll also get the new values.

The short answer is: no!

The long answer is:  3ds max hides complexity. Before per-pixel handling via programmable pixel-shaders became available on consumer gfx cards, shading components across the triangle were mainly calculated by interpolating the value between the three vertices. A triangle is flat and thus you can interpolate in a linear/straight way. For example the vertex colors and normals.

Now, if you have a mesh inside 3ds max – let's say a cube in it's default state. It has 6 smoothing groups, because there are hard edges between each face. How many normals do you need for each corner vertex? Each corner has 3 faces – each of them pointing to another direction and having "hard" seams at it's borders.

We need 3 normals for all 8 corners … that's 24 vertices. Ok, now convert it to an 'editable poly', go into the face sub-level and hit CTRL+a to select all faces. Hit "clear all" and then smoothing group "1" in order to assign a single smoothing group to all faces. Export this one and load it into Virtools. And?

Oh, it ain't 24 anymore but not 8 neither? Yes! That's because there are not only normals stored in the vertices but also UV coordinates and color/material information. In 3ds max do then the following:

  • add the "UV Unwrap" modifier to the cube
  • go into face sub-level mode
  • select all
  • open the "Edit…" dialog
  • select Mapping -> Unfold Mapping ('walk to closest face') -> Ok
  • You now have a cross-like UV layout
  • go into vertex sub-level mode
  • select through each vertex and notice that sometimes another one is highlighted in blue
  • right click and select "target weld" form the context menu
  • now weld each vertex to it's "blue partner" in case it has one

Import the smoothed cube that has no UV seams into Virtools … … … what does the mesh setup say? 8 vertices, finally !!!


I hope this little tutorial has shed some light on the topic therefore you should now be able to understand better why there might be differences in vertex count between Virtools and 3ds max.

You added a couple of BG/VSL BBs from your resource to your composition. Then you hit play …. and oops … a new console message is there, saying something like "input error!". 

Ok, maybe you forgot to attach a local parameter to one of the BBs … but where? To make a long story short, always prefix you error message with a context identifier. For example, you write a VSL BB that modifies a texture … it might happen that you, or somebody else using that BB, will forget to attach a parameter to it and dang your code creates an exception if you don't check it.


    if( NULL != sourceTexture  )
       // my code here
        bc.OutputToConsole("BB_NameHere: Input error! No source texture available");


If you want to check for availability of objects using the schematic, you can use my VSL BB TestForNull

Did you know ….

.. that you can reset the current scene with CTRL & BACKSPACE. This is similar to the "IC<|" Button. In case you are using multiple scenes, than you may want to lunch the level instead the scene that was running last which is still active using the button. So, instead of going into the level manager and hit the Level-Button, you can hit the keyboard combo:


Did you know ….

.. there is another "hidden" camera mode for the 3D Layout. I am using this quite often, when I need to travel in a bigger scene (especially as you don't need to hold anything if you want to go straight ahead all the time):

If you hit the 'Y' key during the author mode in the 3d Layout, it gets enabled or disabled. It's like the old-school VRML Walk/Fly modes: move the mouse to the top window border to go forward, move the mouse to the middle of the screen to stop, move the mouse to the bottom of the window to go backwards etc. There is also  a little trick if you want a bit more forward-speed: move the mouse to the bottom of the screen and then hit the 'y' to enable the mode.

While being in this mode, you can also look-around with the mouse while holding the left-mouse-button or pan using the right-mouse-button.